CO-DASH MCP

#Overview

MCP (Model Context Protocol) lets an AI agent discover and call tools on a remote server through a JSON-RPC 2.0 envelope. CO-DASH implements the streamable-HTTP transport on a single POST route; the same workspace API key used for the REST API also gates MCP.

The MCP surface is intentionally read-only. Account creation, AI-provider credentials, and automations remain on the REST API and are documented below under External REST API.

#Quickstart

Provision a workspace, attach a data source, and call the first tool in five steps.

#1. Register an agent workspace

The registration endpoint is public and rate limited. It returns a kv_live_… key once. Store it server-side immediately — the plaintext is unrecoverable.

curl -sS https://p-api.kvants.ai/api/agents/register \
  -H "content-type: application/json" \
  -d '{
    "name": "research-agent",
    "keyName": "research-agent-prod"
  }'

#2. Connect data sources

MCP reads what the REST API provisions. Attach a read-only exchange account before expecting portfolio tools to return data.

curl -sS https://p-api.kvants.ai/api/accounts \
  -H "authorization: Bearer $KVANTS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name":      "Main Binance",
    "venue":     "binance",
    "apiKey":    "$BINANCE_API_KEY",
    "apiSecret": "$BINANCE_API_SECRET"
  }'

#3. (Optional) Add AI-provider keys

Required only if the workspace uses model-backed CO-DASH features. Not needed for MCP read tools.

curl -sS https://p-api.kvants.ai/api/settings/ai-keys \
  -H "authorization: Bearer $KVANTS_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "provider": "anthropic", "key": "$ANTHROPIC_API_KEY" }'

#4. Initialize and call your first tool

Run the protocol handshake, list scoped tools, then call one.

curl -sS https://p-api.kvants.ai/mcp \
  -H "authorization: Bearer $KVANTS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "clientInfo": { "name": "my-agent", "version": "1.0.0" }
    }
  }'

curl -sS https://p-api.kvants.ai/mcp \
  -H "authorization: Bearer $KVANTS_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": "tools", "method": "tools/list" }'

curl -sS https://p-api.kvants.ai/mcp \
  -H "authorization: Bearer $KVANTS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "pnl-7d",
    "method": "tools/call",
    "params": {
      "name": "get_pnl_by_symbol",
      "arguments": { "days": 7, "limit": 25 }
    }
  }'

#Authentication

Every MCP and REST request carries the workspace API key in one of two headers. Both forms are equivalent; Authorization is preferred for clients that already speak Bearer auth.

Bearer tokens that do not start with kv_live_ are treated as web-app JWTs, not external API keys. Keys can be additionally restricted by expiry, source-IP allowlist, and account allowlist — all enforced server-side.

#Scopes

#Client configuration

Any MCP client that speaks streamable HTTP and supports a custom Authorization header works without a transport adapter. Point it at https://p-api.kvants.ai/mcp and send the workspace key.

{
  "mcpServers": {
    "co-dash": {
      "url": "https://p-api.kvants.ai/mcp",
      "headers": {
        "Authorization": "Bearer kv_live_..."
      }
    }
  }
}

Both Authorization: Bearer kv_live_… and x-api-key: kv_live_… are accepted. Do not send both — when both are present, x-api-key wins.

#Protocol

MCP is JSON-RPC 2.0 over a single POST route. The server supports these methods:

Supported protocol versions: 2025-11-25 (default), 2025-06-18, 2025-03-26, 2024-11-05. The server echoes whichever version the client requested if it's in the supported set.

#Tool output envelope

Every successful tools/call returns:

{
  "jsonrpc": "2.0",
  "id": <request id>,
  "result": {
    "content": [{ "type": "text", "text": "<json-stringified output>" }],
    "structuredContent": <object>,
    "isError": false
  }
}

Parse structuredContent for deterministic data — the content[].text member is a JSON-stringified mirror for model consumption. Tool-level validation errors come back as isError: true on the same envelope (not as a JSON-RPC error).

#MCP error codes

#Tools

Seven read-oriented tools. Each defines its own argument schema with zod, rejects unknown keys, and re-checks scope before reading data. A key with the broad workspace:read scope can call every tool; narrower keys only see matching tools in tools/list.

{
  "count": 1,
  "accounts": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "name": "Main Binance",
      "venue": "binance",
      "denomination": "USD",
      "portfolioId": null,
      "tags": ["cta"],
      "isActive": true,
      "status": "connected",
      "lastBalanceUsd": 1234.56,
      "lastCheckedAt": "2026-05-15T00:00:00.000Z",
      "createdAt": "2026-05-01T00:00:00.000Z",
      "updatedAt": "2026-05-15T00:00:00.000Z"
    }
  ]
}

{
  "timestamp": "2026-05-15T00:00:00.000Z",
  "accountCount": 3,
  "navUsd": 1234567.89,
  "grossExposureUsd": 2000000,
  "netExposureUsd": 500000,
  "longExposureUsd": 1250000,
  "shortExposureUsd": 750000,
  "futuresUpnlUsd": 4321,
  "navBtc": 24.5,
  "navEth": 380.2,
  "btcPrice": null,
  "ethPrice": null
}

{
  "count": 720,
  "days": 30,
  "truncated": false,
  "accountIds": ["00000000-0000-4000-8000-000000000001"],
  "points": [
    {
      "timestamp": "2026-04-15T00:00:00.000Z",
      "nav": 1200000,
      "grossExposure": 1800000,
      "netExposure": 400000
    }
  ]
}

{
  "window": {
    "from": "2026-05-14T00:00:00.000Z",
    "to": "2026-05-15T00:00:00.000Z",
    "hours": 24,
    "days": 1
  },
  "filters": {
    "accountIds": ["00000000-0000-4000-8000-000000000001"],
    "symbols": [],
    "eventTypes": []
  },
  "totals": {
    "eventCount": 1240,
    "notionalUsd": 9800000,
    "feesUsd": 4200,
    "realizedPnlUsd": -8500,
    "fundingUsd": -120,
    "forcedCloseCount": 0
  },
  "byAccount": [ /* per-account totals */ ],
  "bySymbol": [ /* per-symbol totals */ ]
}

{
  "count": 25,
  "totalSymbolCount": 25,
  "window": {
    "from": "2026-05-08T00:00:00.000Z",
    "to": "2026-05-15T00:00:00.000Z",
    "hours": 168,
    "days": 7
  },
  "rows": [
    {
      "symbol": "BTC-PERP",
      "accountIds": ["00000000-..."],
      "accountNames": ["Main Binance"],
      "realizedPnlUsd": 1230.45,
      "fundingUsd": -42.10,
      "feesUsd": 88.20,
      "netPnlUsd": 1100.15
    }
  ],
  "truncated": false
}

{
  "count": 100,
  "nextCursor": "eyJsYXN0VHM...",
  "window": {
    "from": "2026-02-14T00:00:00.000Z",
    "to": "2026-05-15T00:00:00.000Z",
    "hours": 2160,
    "days": 90
  },
  "rows": [
    {
      "id": "evt_01HK...",
      "accountId": "00000000-...",
      "accountName": "Main Binance",
      "symbol": "BTC-PERP",
      "eventType": "trade",
      "occurredAt": "2026-05-15T00:00:00.000Z",
      "side": "buy",
      "qty": 0.25,
      "price": 65000,
      "notionalUsd": 16250,
      "realizedPnlUsd": 0,
      "feeUsd": 6.5
    }
  ],
  "provenance": { /* source tables, fallbacks, applied filters */ }
}

{
  "count": 25,
  "window": {
    "from": "2026-04-15T00:00:00.000Z",
    "to": "2026-05-15T00:00:00.000Z",
    "hours": 720,
    "days": 30
  },
  "rows": [
    {
      "id": "evt_01HK...",
      "accountId": "00000000-...",
      "accountName": "Main Binance",
      "symbol": "ETH-PERP",
      "eventType": "liquidation",
      "occurredAt": "2026-04-20T03:12:00.000Z",
      "netPnlImpactUsd": -18500,
      "notionalUsd": 95000
    }
  ],
  "provenance": { /* ... */ }
}

#External REST API

The same workspace API key authenticates the full REST surface. REST writes provision resources (accounts, AI keys, automations); REST reads expose data MCP also covers, plus the full Grafana dataset and bulk exports.

#Conventions

Most successful responses use a uniform envelope. Errors always use the same shape with success: false. Treat the error string as human-readable; rely on the HTTP status for control flow.

// success
{ "success": true, "data": <endpoint-specific payload> }

// error
{ "success": false, "error": "human-readable message" }

Exceptions: GET /health/*, GET /api/status, and most GET /api/grafana/* routes return the payload at the top level (no wrapper). Inspect HTTP status first there.

• Timestamps are ISO 8601 / RFC 3339 UTC strings. PnL-analysis endpoints also accept date-only strings like 2026-04-13.
• Money values are numbers, not strings. USD unless a *Btc / *Eth field name says otherwise.
• Percent fields are percentages, not fractions. 8.32 means 8.32%, not 0.0832.
• Forensics endpoints echo the resolved window in data.window. When from/to are omitted, the server substitutes a 90-day default — inspect window.defaulted before narrating per-symbol detail.
• Cursor-paginated endpoints (/api/trade-events, /api/forensics/forced-events) skip the default window on subsequent pages and return window: null.

#Read endpoints

Grouped by scope family. Grafana read routes (GET /api/grafana/*) are also API-key accessible under the relevant read scope and back the same datasets the in-app dashboard renders.

#Write endpoints

#HTTP errors

#Rate limits

Two one-minute sliding-window limits apply to API-key traffic:

• Credential attempt: 300 requests / minute / caller IP on any request that carries an API-key credential (valid or invalid). Coarse IP backstop.
• Read usage: 100 requests / minute / API key hash on authenticated reads. Current usage is surfaced in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers.

When limited, the response is 429 with a Retry-After header. Honor it — don't tight-loop.

#Operations

Treat MCP as a financial data boundary. The route uses the same expiration, IP allowlist, account allowlist, and rate-limit middleware as the external API.

• Keep kv_live_ keys out of prompts, logs, browser storage, and client-side bundles.
• Use account allowlists when a user or agent should only inspect a subset of exchange accounts.
• Prefer summary or live scopes unless the agent truly needs raw trade events.
• Treat every MCP response as data: parse structuredContent, validate ranges, and keep evidence links in your own audit trail.
• Set timeouts around tool calls. Retry only idempotent reads with bounded backoff.
• Rotate the workspace key when a user, agent, tenant, or execution environment is retired.