MCP server¶

The Developer API is also available as a remote Model Context Protocol server, so Claude Code, Cursor, Claude Desktop and other MCP clients can check your wallet, order agents and chat with them as tools, with no wrapper code.


Endpoint	`https://api.mintbot.ai/mcp`
Transport	Streamable HTTP, stateless, JSON responses (no SSE stream, no session id)
Protocol versions	`2025-06-18` (latest), `2025-03-26`, `2024-11-05`
Auth	the same API key as the REST API: `X-API-Key: mb_…` or `Authorization: Bearer mb_…`
Rate limit, scopes, errors	exactly the REST ones — every tool call runs the matching `/v1` endpoint

Create a key on the developer portal (or with POST /v1/signup) first.

Connect a client¶

Claude Code¶

claude mcp add --transport http mintbot https://api.mintbot.ai/mcp \
  --header "X-API-Key: mb_xxxxxxxxxxxxxxxx"

Cursor¶

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "mintbot": {
      "url": "https://api.mintbot.ai/mcp",
      "headers": { "X-API-Key": "mb_xxxxxxxxxxxxxxxx" }
    }
  }
}

Claude Desktop (via mcp-remote)¶

claude_desktop_config.json:

{
  "mcpServers": {
    "mintbot": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.mintbot.ai/mcp",
        "--header", "X-API-Key:${MINTBOT_API_KEY}"
      ],
      "env": { "MINTBOT_API_KEY": "mb_xxxxxxxxxxxxxxxx" }
    }
  }
}

Clients that can only set a bearer token work too — send the same key in an Authorization: Bearer header instead of X-API-Key.

Check the connection¶

One curl tells you whether the key and the endpoint are good — it lists the tools without spending anything:

curl -s https://api.mintbot.ai/mcp \
  -H "X-API-Key: mb_xxx...xxx" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

Tools¶

Tool	REST endpoint	Spends money	Notes
`get_plans`	`GET /v1/plans`	no	packages, price, bundled LLM credit
`get_prices`	`GET /v1/prices`	no	live BTC / XMR in USD
`list_models`	`GET /v1/models`	no	LLM models + per-MTok prices
`get_account`	`GET /v1/account`	no	account id, e-mail
`get_wallet`	`GET /v1/wallet`	no	EUR balance + last 50 ledger rows
`get_wallet_spend`	`GET /v1/wallet/spend`	no	`days` (default 30)
`create_wallet_topup`	`POST /v1/wallet/topup`	no	returns a `checkout_url` a human opens to pay
`order_agent`	`POST /v1/agents`	yes	charged from the wallet at once
`list_agents`	`GET /v1/agents`	no
`get_agent`	`GET /v1/agents/{agent_id}`	no
`get_agent_usage`	`GET /v1/agents/{agent_id}/usage`	no	per-model LLM spend, `days`
`add_agent_credit`	`POST /v1/agents/{agent_id}/credit`	yes	wallet → agent LLM credit
`chat_with_agent`	`POST /v1/agents/{agent_id}/chat`	uses agent LLM credit	can take up to two minutes
`list_ssh_keys`	`GET /v1/ssh-keys`	no
`add_ssh_key`	`POST /v1/ssh-keys`	no	id → `ssh_key_id` for a headless agent

Arguments are the same fields as the REST request body (or query string for GET); path parameters such as agent_id are plain arguments.

Money-spending tools are marked destructive

order_agent and add_agent_credit carry destructiveHint: true and are not idempotent. Well-behaved clients ask you before running them; keep that confirmation switched on. For a hard limit, keep only as much money in the wallet as the agent may spend.

Not exposed over MCP on purpose: deleting agents or SSH keys, signup, webhooks and the legacy crypto /v1/orders flow. Use the REST API for those.

Results and errors¶

A successful call returns the REST JSON as text plus structuredContent (a list is wrapped as {"items": [...]}).
A failed REST call (400, 402 insufficient_funds, 403 missing scope, 404, 409 no_wallet, 429, …) comes back as a tool result with isError: true. The text is HTTP <status> from <METHOD> <path>: <REST error body> followed by a one-line hint on what to do next, so the model can read the detail code and knows whether to top up, fix an id, wait, or stop.
Bad arguments never reach the API: a wrong type, an unknown argument or an out-of-range amount is JSON-RPC error -32602 naming the field and the allowed values. The ranges the tools advertise (top-up and credit amounts, days) are the live server limits, so a model can keep inside them before it calls.
A transport failure — for example chat_with_agent waiting on a slow agent — is likewise a tool result with isError: true, never a broken response.
A missing or invalid key is HTTP 401 for the whole request, with a WWW-Authenticate challenge and a message naming the header to send. GET and DELETE on /mcp answer 405: the server is stateless and JSON-only, so there is no stream to open and no session to delete.
Each tool call counts as one request against the key's rate limit and shows up in the key's request log; initialize and tools/list don't count.