> ## Documentation Index
> Fetch the complete documentation index at: https://dev-docs.multihopper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP servers

> Connect AI agents to MultiHopper: the API server acts, the docs server reads

MultiHopper runs two hosted **Model Context Protocol (MCP)** servers:

| | API server | Docs server |
| - | - | - |
| URL | `https://multihopper.com/api/mcp` | `https://dev-docs.multihopper.com/mcp` |
| Does | estimates, creates and tracks transfers, builds custom routes, saves route templates | searches and reads these docs and the OpenAPI spec |
| Auth | your API key | none |

Connect both: the agent reads how the API works from the docs server and calls it through the API server.

## The API server

```
https://multihopper.com/api/mcp
```

It uses the Streamable HTTP transport and is stateless: there is no session, and no server-initiated
stream. Authenticate with your API key in the `x-api-key` header, or as `Authorization: Bearer <key>`.
Each tool calls one REST endpoint with your key. Its rules, rate limits, `Idempotency-Key` handling and
error codes are the API's own. An API error comes back as a tool result with `isError: true` and the
API's `{ "error": { "code", "message" } }` body.

> [!WARNING]
>
> **The server never holds a wallet key.** `prepare_transfer` returns **unsigned** transactions. Your
> agent signs them with the `sourceOwner` wallet and broadcasts them itself (see
> [signing](https://dev-docs.multihopper.com/guides/agentic-integration.md#transaction-signing)), then calls `confirm_broadcast`. An API key
> alone cannot move funds, but it can create transfers and route templates in your integration. Keep it
> secret like any credential.

### Connect

> [accordion] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http multihopper https://multihopper.com/api/mcp \
>   --header "x-api-key: $MH_KEY"
> ```

> [accordion] Claude Desktop
>
> In `claude_desktop_config.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "multihopper": {
>       "command": "npx",
>       "args": ["-y", "mcp-remote", "https://multihopper.com/api/mcp", "--header", "x-api-key:${MH_KEY}"],
>       "env": { "MH_KEY": "mh_live_..." }
>     }
>   }
> }
> ```

> [accordion] Cursor
>
> In `~/.cursor/mcp.json` (or the project's `.cursor/mcp.json`):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "multihopper": {
>       "url": "https://multihopper.com/api/mcp",
>       "headers": { "x-api-key": "mh_live_..." }
>     }
>   }
> }
> ```

> [accordion] VS Code (Copilot)
>
> In `.vscode/mcp.json`. VS Code prompts for the key once and stores it:
>
> ```json theme={null}
> {
>   "inputs": [
>     { "type": "promptString", "id": "mh-key", "description": "MultiHopper API key", "password": true }
>   ],
>   "servers": {
>     "multihopper": {
>       "type": "http",
>       "url": "https://multihopper.com/api/mcp",
>       "headers": { "x-api-key": "${input:mh-key}" }
>     }
>   }
> }
> ```

> [accordion] Any MCP client
>
> POST JSON-RPC 2.0 to `https://multihopper.com/api/mcp` with your key in `x-api-key`. Supported
> protocol versions: `2025-06-18`, `2025-03-26` and `2024-11-05`. `initialize` and `tools/list` work
> without a key; every `tools/call` needs one.

### Tools

| Tool | Calls | |
| - | - | - |
| `list_hop_library` | `GET /hop-library` | Wallets a custom route can use, and its bundles |
| `estimate_transfer` | `POST /transfers/estimate` | Fees and required SOL; with `route`, a free dry run of a custom route |
| `create_transfer` | `POST /transfers` | One recipient or up to 20 destinations; `route` or `routeTemplateId` optional |
| `prepare_transfer` | `POST /transfers/{transferId}/prepare` | Unsigned transactions, for your wallet to sign and broadcast |
| `confirm_broadcast` | `POST /transfers/{transferId}/confirm-broadcast` | Report signatures; the keeper takes over |
| `get_transfer` | `GET /transfers/{transferId}` | Status, phase, hops, payouts |
| `get_transfer_by_external_id` | `GET /transfers/by-external/{externalId}` | The same, by your `externalId` |
| `list_transfers` | `GET /transfers` | Your transfers |
| `list_route_templates`, `get_route_template` | `GET /route-templates[/{templateId}]` | Your saved routes |
| `create_route_template`, `update_route_template`, `delete_route_template` | `POST` / `PATCH` / `DELETE /route-templates` | Save, change and delete routes |
| `get_usage` | `GET /usage` | Volume and revenue share |

Each tool's input schema is built from the [OpenAPI spec](https://dev-docs.multihopper.com/api-reference/introduction.md), so its fields
are the endpoint's fields. Mutating tools take an optional `idempotencyKey`. Send the same key to retry
a call safely. Without one, a new key is generated, so a retried call runs again. For
`create_transfer`, an `externalId` also makes retries safe.

### A typical agent run

1. `list_hop_library` → choose wallets or bundles.
2. `estimate_transfer` with `route` → fix what `MH_018` lists until it passes, and check
   `sol.requiredSolUpFrontLamports`.
3. `create_transfer` with the same `route` and an `externalId`. Or save it first with
   `create_route_template` and pass `routeTemplateId`.
4. `prepare_transfer` → sign and broadcast with your wallet, in the order the tool describes.
5. `confirm_broadcast`, then `get_transfer` until `status` is `completed`.

## The docs server

The documentation is available as a hosted MCP server too. Connect any MCP-compatible AI client to
search docs, read API references, and explore code examples in real time.

```
https://dev-docs.multihopper.com/mcp
```

***

### Connect the docs server

> [accordion] Claude Desktop
>
> Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) and add:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "multihopper-docs": {
>       "command": "npx",
>       "args": ["-y", "mcp-remote", "https://dev-docs.multihopper.com/mcp"]
>     }
>   }
> }
> ```
>
> Restart Claude Desktop. The `search_multi_hopper` and `query_docs_filesystem_multi_hopper` tools will be available in every conversation.

> [accordion] Cursor
>
> Open **Cursor Settings → MCP** and add a new server:
>
> * **Name:** `multihopper-docs`
> * **URL:** `https://dev-docs.multihopper.com/mcp`
>
> Or run the Mintlify install command in your terminal:
>
> ```bash theme={null}
> npx mcp add dev-docs.multihopper.com
> ```

> [accordion] VS Code (Copilot)
>
> Add to your `.vscode/mcp.json` or user settings:
>
> ```json theme={null}
> {
>   "servers": {
>     "multihopper-docs": {
>       "type": "sse",
>       "url": "https://dev-docs.multihopper.com/mcp"
>     }
>   }
> }
> ```

> [accordion] Any MCP client
>
> The server uses the standard **SSE transport**. Point your client at:
>
> ```
> https://dev-docs.multihopper.com/mcp
> ```
>
> No authentication is required for public documentation pages.

***

### Docs server tools

#### `search_multi_hopper`

Searches across the MultiHopper knowledge base to find relevant information, code examples, API references, and guides.

Use this tool for broad or conceptual queries — e.g. *"how does the orchestrator work"*, *"what is keeperFundingTx"*, or *"error MH\_039"*. Returns contextual snippets with titles and links to the source pages.

**Example prompts that trigger this tool:**

* "How do I estimate fees before creating a transfer?"
* "What is the broadcast order for prepared transactions?"
* "What does phase `recoverable` mean?"
* "How do I build a custom route through exchange wallets?"

***

#### `query_docs_filesystem_multi_hopper`

Runs read-only shell-style queries against a virtualized filesystem containing all MultiHopper documentation pages and the OpenAPI spec.

Use this tool when you need **exact content** from a specific page, regex matches across the docs, or structural exploration.

**Supported commands:** `rg`, `grep`, `find`, `tree`, `ls`, `cat`, `head`, `tail`, `stat`, `wc`, `sort`, `uniq`, `cut`, `sed`, `awk`, `jq`

**Useful commands:**

```bash theme={null}
# See the full docs structure
tree / -L 2

# Read a specific page
head -100 /quickstart.mdx
cat /api-reference/transfers/prepare.mdx

# Search for a keyword across all docs
rg -il "keeperFundingTx" /

# Show lines around a match with context
rg -C 3 "MH_039" /api-reference/

# List all OpenAPI endpoints
cat /api-reference/openapi.json | jq '.paths | keys'

# Read multiple pages in one call
head -80 /quickstart.mdx /guides/agentic-integration.mdx
```

> [!NOTE]
>
> Each call is **stateless** — the working directory always resets to `/`. Chain commands with `&&` or use absolute paths if you need to navigate a subdirectory.

***

### Example: reading the docs

Here's how an AI agent would use both tools to answer *"how do I sign and broadcast a prepared transfer?"*:

1. **`search_multi_hopper`** — `"sign broadcast prepared transactions"` → finds `/guides/agentic-integration` and `/api-reference/transfers/prepare`
2. **`query_docs_filesystem_multi_hopper`** — `head -150 /guides/agentic-integration.mdx` → reads the full signing code examples

The search tool narrows scope; the filesystem tool reads the full page. Use them together.

> [card] [Agentic Integration Guide](https://dev-docs.multihopper.com/guides/agentic-integration.md)
>
> Full guide for autonomous agents — signing, broadcasting, and the complete TypeScript/Python loop.

> [card] [API Reference](https://dev-docs.multihopper.com/api-reference/introduction.md)
>
> All endpoints, error codes, and rate limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.