> For the complete documentation index, see [llms.txt](https://agentdex.gitbook.io/agentdex-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agentdex.gitbook.io/agentdex-docs/developers/mcp-server.md). # MCP server The Model Context Protocol (MCP) server is AgentDex's headline interface. Any MCP-capable client — Claude Code, Claude Desktop, Cursor, Goose, OpenAI agents, custom frameworks — connects to one URL with one key and can read state and (with the right scope) trade. Tool schemas are typed; the same per-key permission system that scopes REST also scopes which tools your agent sees. ### Why MCP, not just REST A traditional exchange API requires writing a tool-calling adapter per endpoint, with its own argument schema and error handling, before an LLM can use it. The agent doesn't natively know what `place-order` accepts; the adapter has to express it. MCP solves this at the protocol level. The server publishes typed JSON schemas alongside each tool. The agent introspects, sees what's available and what each tool needs, and calls them directly. There is no second layer to maintain. Because the server filters tools by **the calling key's permissions**: * A `ro` key sees only read tools — the agent literally cannot attempt `place_order`. * A `rw` key with `instruments: ["BTC_USDT_PERPETUAL"]` sees `place_order`, but an order on `ETH_...` is rejected server-side before reaching the matching engine. * A `rw` key with `order_quoted_volume_lte: 100` rejects any order above $100 — the agent can't bypass it by chunking. This is the operational basis for handing an agent a bounded mandate. ### Endpoint and auth {% code title="MCP endpoint" %} ``` URL: https://agentdex.xyz/mcp Header: X-Api-Key: ``` {% endcode %} JSON-RPC over HTTP (`POST`). The MCP client handles `initialize` and `tools/list` for you; you only call tools. ### Tools The server exposes only the tools the key can use. Full list: | Tool | Scope | What it does | | --------------------- | ----- | ---------------------------------------------------------------------- | | `get_exchange_status` | `pub` | Health check. Returns `{ "status": "ok" }` when healthy. | | `get_time` | `pub` | Server time in Unix milliseconds (UTC). | | `get_instruments` | `pub` | All instruments visible to this key, with default + maximum leverage. | | `get_instrument` | `pub` | One instrument by id. | | `get_ticker` | `pub` | Mark / index / fair / last / 24h stats for an instrument. | | `get_tickers` | `pub` | All tickers in one call. | | `get_orderbook` | `pub` | Bids + asks (price + USDT quantity) for an instrument. | | `get_balances` | `ro` | `available`, `on_hold`, `unrealized_pnl` in USDT. | | `get_positions` | `ro` | Open positions: side, value, entry, margin, leverage, liq price, uPnL. | | `get_permissions` | `ro` | The effective scope and limits on the current key. | | `place_order` | `rw` | Place a market or limit order, sized in USDT. | | `change_leverage` | `rw` | Set leverage for an instrument (cross margin). | | `cancel_all_orders` | `rw` | Cancel all active orders for an instrument. | #### Tool schemas Inputs and outputs follow JSON Schema. For `place_order`: {% code title="place\_order schema" %} ```json { "name": "place_order", "arguments": { "instrument_id": "BTC_USDT_PERPETUAL", "side": "buy" | "sell", "type": "market" | "limit", "amount": 50, "price": 80500 } } ``` {% endcode %} `price` is required for `limit`, optional for `market`. `amount` is **USDT quoted volume**. Response: {% code title="place\_order response" %} ```json { "order_id": "27da84bc-30dd-461f-a333-651ce248082a", "avg_price": "80525.4", "amount": "49.9", "filled": "49.9", "remaining": "0" } ``` {% endcode %} If a `rw` key would exceed a configured limit (`leverage`, `order_quoted_volume`, instrument allowlist), the call returns an error before the matching engine sees it. ### End-to-end example: plug Claude Code into AgentDex 1. **Create a tightly-scoped key.** From the web UI or the Auth API: 
curl -X POST -H "Authorization: Bearer $SESSION" \
     -H "Content-Type: application/json" \
     https://agentdex.xyz/api/keychain/api-keys \
     -d '{
       "label": "my-claude-agent",
       "permissions": {
         "scope": "rw",
         "expiration": "2026-12-31T00:00:00Z",
         "instruments": ["BTC_USDT_PERPETUAL"],
         "leverage_gte": 10, "leverage_lte": 20,
         "order_quoted_volume_gte": "1",
         "order_quoted_volume_lte": "100"
       }
     }'
The response returns `key` once. Store it. 2. **Add the MCP server to Claude Code:** 
claude mcp add agentdex \
     --url https://agentdex.xyz/mcp \
     --header "X-Api-Key=$AGENTDEX_KEY"
3. **Ask the agent:** *"On AgentDex, what's BTC trading at, and what's my current position? Then short $50 if mark is above $80 000."* The agent calls `get_ticker`, `get_positions`, then `place_order` with `amount=50, side=sell, type=market` — all bounded by the key's limits. 4. **Revoke when done:** 
curl -X DELETE -H "Authorization: Bearer $SESSION" \
     https://agentdex.xyz/api/keychain/api-keys/$SHORT_TOKEN
### Recommended patterns for agentic use * **One key per agent.** Clean revocation if the agent misbehaves. * **Tight limits on every key.** Allowlist one instrument, set `order_quoted_volume_lte` to your maximum acceptable single trade. * **Use `get_permissions` first.** Don't trust an agent's assumption about what it can do — read the actual scope on the key. * **Mirror trade history into your own log.** The on-chain canonical log will be public after Phase 4 of [Validator and verifiability](/agentdex-docs/under-the-hood/validator-and-verifiability.md), but you should have your own copy too. ### Differences vs. REST * **One-shot semantics.** MCP tools return on completion; no long-lived subscription. For live updates, use WebSocket alongside MCP. * **Simpler auth.** One header, one URL — no JWT lifecycle. * **Schema-driven.** The agent introspects available tools; you don't hand-write a tool-spec. ### Roadmap Planned improvements to the MCP surface: * **Streaming tools** — push notifications, fills, liquidation alerts as MCP-native events. * **More instruments** — additional perpetual pairs and (later) spot. * **Sub-account / multi-account scoping** on a single key. * **Deeper read tools** — historical fills, order history, account stats. If you're building on the MCP surface and want a specific tool, send a request — that's how priority is set. --- # 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://agentdex.gitbook.io/agentdex-docs/developers/mcp-server.md?ask=&goal= ``` `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.