> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compasslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Connect Claude, Cursor, or any MCP client to the Compass API — every DeFi product as native agent tools, over one URL, with nothing to install.
## What is the Compass MCP server?
The Compass API hosts a [Model Context Protocol](https://modelcontextprotocol.io) server at:
```text theme={"system"}
https://api.compasslabs.ai/mcp
```
Connect an MCP-speaking client (Claude Code, Claude Desktop, Cursor, ...) and every Compass product — Earn, Credit, swaps, bridging, Global Markets perps, Tokenized Assets — appears as a typed tool the agent can call directly. No SDK, no binary, no code generation.
Like the rest of the API, the MCP server is **non-custodial**: tools never sign or broadcast. Read tools return data; action tools return an **unsigned transaction** (or EIP-712 typed data) that you sign with your own wallet.
The server speaks MCP's Streamable HTTP transport; `https://api.compasslabs.ai/mcp` and `.../mcp/` both work. Authentication is your regular Compass API key sent as an `X-API-Key` header — get a **free key** [here](https://api.compasslabs.ai/auth/get_api_token).
## Connect a client
```bash theme={"system"}
claude mcp add --transport http compass https://api.compasslabs.ai/mcp \
--header "X-API-Key: YOUR_API_KEY"
```
Then ask Claude something like *"what are the best USDC vaults on Base?"* — it picks the right Compass tool on its own.
Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
```json theme={"system"}
{
"mcpServers": {
"compass": {
"url": "https://api.compasslabs.ai/mcp",
"headers": { "X-API-Key": "YOUR_API_KEY" }
}
}
}
```
Claude Desktop reaches header-authenticated remote servers through the `mcp-remote` bridge. Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
```json theme={"system"}
{
"mcpServers": {
"compass": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://api.compasslabs.ai/mcp",
"--header", "X-API-Key:${COMPASS_API_KEY}"
],
"env": { "COMPASS_API_KEY": "YOUR_API_KEY" }
}
}
}
```
The server is plain Streamable HTTP — point any MCP client at the URL with the header, or smoke-test with cURL:
```bash theme={"system"}
curl -X POST https://api.compasslabs.ai/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
## What you get
48 tools spanning the Compass products. Names mirror the API operation ids, and descriptions and parameter schemas come from the same OpenAPI source as the [API reference](/v2/api-reference) — `tools/list` is always in sync with the deployed API.
| Group | Tools | Examples |
| ---------------------- | ----- | ------------------------------------------------------------------------------- |
| Earn | 12 | `v2_earn_vaults`, `v2_earn_manage`, `v2_earn_bundle` |
| Credit | 7 | `v2_credit_create_account`, `v2_credit_borrow`, `v2_credit_repay` |
| Bridging (CCTP) | 2 | `v2_cctp_burn`, `v2_cctp_mint` |
| Gas sponsorship | 2 | `v2_gas_sponsorship_prepare`, `v2_gas_sponsorship_approve_transfer` |
| Global Markets (perps) | 14 | `v2_global_markets_perps_market_order`, `v2_global_markets_perps_opportunities` |
| Tokenized Assets | 11 | `v2_tokenized_assets_quote`, `v2_tokenized_assets_transact_buy` |
| On-Ramp (Halliday) | 3 | `v2_onramp_quote`, `v2_onramp_create`, `v2_onramp_status` |
On connect, the server also returns usage instructions to the client (the flow below, amount conventions, chain coverage per product), so well-behaved agents follow the rules without extra prompting.
## The non-custodial flow
1. **Read** — markets, positions, and balances tools return data directly.
2. **Account** — Earn, Credit, and Tokenized Equities act through a per-owner **product account**: call that product's `*_create_account` tool first. It is idempotent and returns `transaction: null` if the account already exists.
3. **Build** — action tools return an unsigned transaction `{to, data, value, ...}`.
4. **Sign & broadcast** — with your own key, for example with Foundry's `cast`:
```bash theme={"system"}
cast send --value --rpc-url $RPC_URL --account my-keystore
```
Some flows sign **EIP-712 typed data** instead of a transaction:
* **Global Markets perps** (Hyperliquid): build the order with `v2_global_markets_perps_market_order` (or `limit_order`, `withdraw`, ...) → sign the returned typed data → submit via `v2_global_markets_perps_execute`. Fund first with `v2_global_markets_perps_deposit`; perps need no product account.
* **Tokenized Assets**: `v2_tokenized_assets_order` → sign → `v2_tokenized_assets_order_submit`. RWA yield assets (e.g. mTBILL) can also be bought or sold directly with `v2_tokenized_assets_transact_buy`/`_sell`, which return a regular unsigned transaction.
* **Gas sponsorship**: call an action with `gas_sponsorship: true` → sign the returned EIP-712 → submit signature and typed data to `v2_gas_sponsorship_prepare` → a sponsor broadcasts, and the owner pays no gas. See [Gas Sponsorship](/v2/Products/gas-sponsorship).
* **On-ramp (browser handoff)**: a fiat card + KYC flow can only render in a browser, so an agent cannot complete it inline. Call `v2_onramp_create` → **present the returned `checkout_url` and `user_instructions` to the user** so they can pay by card → then poll `v2_onramp_status` (with the `payment_id`) until `delivered`. USDC lands in the user's own wallet (non-custodial); continue with the tokenized buy. See [On-Ramp](/v2/Products/On-Ramp).
## Good to know
* **Amounts are decimal token units** (`"1.5"` means 1.5 USDC), never wei. `"ALL"` is not supported — pass an explicit amount.
* **Tokens** go by symbol (`USDC`, `WETH`) or `0x` address; pass the address when a symbol isn't recognized.
* **Chains vary by product**: Earn and Credit cover Ethereum, Base, Arbitrum, HyperEVM, and Tempo; CCTP bridges Ethereum, Arbitrum, and Base; Tokenized Assets settle on Ethereum (RWA buy/sell swaps also on Base); perps run on Hyperliquid.
* **The server is stateless**: every request is self-contained — no sessions to manage, and a 5xx is safe to retry once.
* **Errors**: 4xx bodies are actionable (for example `Unknown token symbol`) — surface them as-is. A 401 means the `X-API-Key` header is missing or invalid.
`https://docs.compasslabs.ai/mcp` is a different server: it searches this documentation site and needs no API key. The server documented on this page — `api.compasslabs.ai/mcp` — is the one that reads on-chain state and builds transactions.
***
The `compass` CLI wraps the same API as subcommands — for terminals, scripts, and CI.
A packaged skill that teaches Claude Code, Cursor, or Codex the Compass workflow end to end.