> For the complete documentation index, see [llms.txt](https://archer-bot.gitbook.io/archer.bot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://archer-bot.gitbook.io/archer.bot/for-builders/overview.md).

# MCP Server

Archer Protocol exposes its tools via a **Model Context Protocol (MCP)** server, allowing AI coding assistants and autonomous agents to interact with Web3 directly from their terminal or IDE.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that enables AI tools to connect to external services. When you connect Claude Code, Cursor, or another MCP-compatible client to Archer's MCP server, the AI gains access to Archer's full suite of Web3 tools — token lookups, price checks, swap quotes, bridge quotes, and transaction execution — all without leaving your development environment.

## What Can You Do?

With Archer's MCP server connected, you can ask your AI assistant to:

* **Check token prices** — "What's the current price of ETH?"
* **Look up tokens** — "Find the contract address for USDC on Arbitrum"
* **Get swap quotes** — "Quote swapping 100 USDC to ETH on Base"
* **Get bridge quotes** — "How much would it cost to bridge 0.5 ETH from Ethereum to Arbitrum?"
* **Check balances** — "What are my token balances across all chains?"
* **Prepare transactions** — "Swap 50 USDC to ETH on Base" (creates a transaction for you to approve in the webapp)

## How It Works

Archer supports two connection models depending on the client:

### Stdio Bridge (Claude Code, Claude Desktop)

Claude Code and Claude Desktop use a lightweight npm package that bridges stdio to Archer's remote server:

```
Your AI Assistant (Claude Code, Claude Desktop)
  |
  | stdio (stdin/stdout)
  |
  v
@archerprotocol/mcp-client (npm package, runs locally)
  |
  | Streamable HTTP (authenticated via API key)
  |
  v
Archer MCP Server (api.archerprotocol.com/mcp)
  |
  | Calls Archer's tools (resolve_token, get_token_price, get_swap_quote, etc.)
  |
  v
Archer Backend (intent parsing, multi-chain execution)
  |
  | If transaction needed:
  v
Webapp Approval Queue  -->  You sign in the browser  -->  Transaction submitted
```

### Direct HTTP/SSE (Cursor, VS Code, Windsurf, etc.)

Most IDE-based clients connect directly to the remote endpoint:

```
Your AI Assistant (Cursor, VS Code, etc.)
  |
  | MCP Protocol (HTTP with x-api-key header)
  |
  v
Archer MCP Server (api.archerprotocol.com/mcp)
  |
  v
(same flow as above)
```

### Why Two Models?

Claude Code's MCP client requires OAuth 2.1 for its internal auth state machine to transition to "authenticated" when using `type: "http"` or `type: "sse"` transports. Static API key headers authenticate at the HTTP layer but don't satisfy Claude Code's auth state tracking. The stdio bridge solves this cleanly — Claude Code launches the bridge as a subprocess (like any stdio MCP server) and the bridge handles authentication with Archer's API. This is the same pattern used by Stripe, Supabase, Neon, and other production MCP providers.

### Transaction Approval Flow

When your AI assistant initiates a transaction (swap, bridge, or send):

1. The MCP server prepares the unsigned transaction and creates a **Pending Approval**
2. Your Archer webapp shows a notification with the transaction details
3. You review and **Approve** or **Reject** the transaction in the browser
4. If approved, the transaction is signed with your Privy embedded wallet and submitted on-chain
5. The MCP server receives the result and reports back to your AI assistant

This human-in-the-loop model ensures you always have full control over your funds. No transaction is ever submitted without your explicit consent.

## Supported Tools

| Tool                     | Description                                       | Requires Approval |
| ------------------------ | ------------------------------------------------- | :---------------: |
| `resolve_token`          | Look up token metadata (address, decimals, chain) |         No        |
| `get_token_price`        | Get current USD price for any token               |         No        |
| `get_user_balances`      | Fetch your balances across all chains             |         No        |
| `get_chain_capabilities` | List supported chains and their configs           |         No        |
| `get_swap_quote`         | Get a swap quote without executing                |         No        |
| `get_bridge_quote`       | Get a bridge quote without executing              |         No        |
| `check_feasibility`      | Validate balance + chain compatibility            |         No        |
| `check_approval_status`  | Check status of a pending transaction approval    |         No        |
| `prepare_swap_tx`        | Build a swap transaction for signing              |      **Yes**      |
| `prepare_bridge_tx`      | Build a bridge transaction for signing            |      **Yes**      |
| `prepare_send_tx`        | Build a send/transfer transaction for signing     |      **Yes**      |

## Getting Started

1. [Create an API Key](/archer.bot/for-builders/developer-portal.md) in the Archer webapp
2. [Connect your client](/archer.bot/for-builders/overview/client-setup.md) (Claude Code, Cursor, VS Code, etc.)
3. Start prompting your AI assistant with Web3 queries

## Compute Units (CU)

Every MCP tool call consumes **Compute Units** (CU). Your account includes a free monthly CU allowance. Read-only operations (price checks, token lookups) cost fewer CUs than transaction operations (swaps, bridges).

See the [Developer Portal](/archer.bot/for-builders/developer-portal.md) for usage tracking and billing details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://archer-bot.gitbook.io/archer.bot/for-builders/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.