MCP for AI agents

MCP (Model Context Protocol) is a standard way for AI assistants to call tools. VortexDeployer runs an MCP server. Each REST call is one tool, with the same scopes and limits.

Before you start#

• Make an API key in the app. See API overview & keys.
• Pick its scopes: read to look, trade to trade and run tasks, launch to launch.

Connect#

Claude Code:

claude mcp add --transport http vortex https://api.vortexdeployer.com/api/v1/mcp \
  --header "Authorization: Bearer vd_…"

Claude Desktop, Cursor and most other clients take a JSON entry:

{
  "mcpServers": {
    "vortex": {
      "url": "https://api.vortexdeployer.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer vd_…" }
    }
  }
}

Claude.ai cannot send a fixed key. Add a custom connector with the address https://api.vortexdeployer.com/api/v1/mcp. Claude then signs in through OAuth, and you pick which of your API keys it acts as. See OAuth for connectors.

Your own code can use any MCP SDK. With the TypeScript one:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(new URL('https://api.vortexdeployer.com/api/v1/mcp'), {
  requestInit: { headers: { Authorization: 'Bearer vd_…' } },
}));
const { tools } = await client.listTools();
const me = await client.callTool({ name: 'me', arguments: {} });

Then ask in plain words, like "Which of my wallets hold SOL?" or "Dry-run a 0.1 SOL buy of this token from wallet 812." The assistant picks the tool and fills in the details.

Tools#

A tool's name is the call's operationId in the OpenAPI document at https://api.vortexdeployer.com/api/v1/openapi.json. Its arguments are the call's path and query fields plus its JSON body, all in one object.

For calls that take an Idempotency-Key header, pass it as the idempotencyKey argument. Do that on every trade. See Limits, retries & errors.

Each tool carries hints for your client. GET tools are marked read-only. Every other tool is marked as one that changes things. Your client can use this to ask you before it runs such a tool.

Some tools have a dry run on by default: launch, claim_cashback, closeout_project, burn_tokens, lock_tokens and convert. Others are real by default: buy, sell, trade_batch, claim_creator_fees and every task you start.

What a call returns#

The result is the REST answer, as text and as structuredContent. _meta has the HTTP status and, on reads and order checks, the key's rate-limit window:

{
  "content": [ { "type": "text", "text": "{ \"user\": { … }, \"key\": { … } }" } ],
  "structuredContent": { "user": { "id": "1", "username": "yourname" }, "key": { "id": "9", "name": "agent", "prefix": "5e6f7a8b", "scopes": ["read"], "settings": {}, "restricted": false } },
  "_meta": { "status": 200, "rateLimit": { "limit": 300, "remaining": 299, "reset": 1758050400 } }
}

A refusal has "isError": true and the same body as REST: code, error and traceId. Read the code before you retry. The codes are in Limits, retries & errors.

{ "isError": true, "content": [ { "type": "text", "text": "{ \"code\": \"insufficient_scope\", \"error\": \"this API key does not have the 'trade' scope\", \"traceId\": \"…\" }" } ] }

Two refusals come from the MCP server itself:

• validation_failed — an unknown tool, a missing path argument like id, an idempotencyKey on a tool that takes none, or an unknown argument on a tool with no body. On a tool with a body, extra arguments go into the body, and the REST route checks them.
• service_unavailable — the call gave no answer in 3 minutes. The work may still finish. Ask again with the same idempotencyKey.

Good to know#

• Same rules as REST. Each tool call is made as the REST call with your key. Scopes, key limits, rate limits and idempotency all apply.
• No session. Every request signs in on its own. A dropped line loses nothing.
• Amounts. On-chain amounts are in base units unless the field says otherwise. amountSol is a plain JSON number in the chain's coin: SOL on Solana, ETH on an EVM chain. For burn_tokens and lock_tokens, amount with amountType: "tokens" is a whole number of base units, like "3500000000", never "1.5". With "percentage" it is a whole number from 1 to 100. A bad amount comes back as "ok": false with the reason in error. See Burn and lock.
• Streams are not tools. For live trades, PnL and balances, use Live streams.
• Usage shows in the app on the API page, Usage tab, under the same key.
• A GET to https://api.vortexdeployer.com/api/v1/mcp gets 405. Only POST works.

See also#

• OAuth for connectors
• Build an agent on the API
• Limits, retries & errors
• Live streams