MCP server

POST /v1/mcp — Streamable HTTP Model Context Protocol endpoint that exposes your Cocobox connections as tools to any MCP client.

Last updated

The Cocobox MCP server lets any Model Context Protocol-aware client (GitHub Copilot in VS Code, Cursor, Zed, opencode, Claude Code, …) call your Cocobox connections as tools — securely, with full audit logging, and with the same sk-coco-* key as the rest of the API.

POST https://api.cocobox.io/v1/mcp Authenticated with Authorization: Bearer sk-coco-…

Transport

Cocobox implements the MCP Streamable HTTP transport:

  • All client → server calls are HTTP POST to /v1/mcp.
  • Server → client streaming uses chunked text/event-stream responses.
  • Sessions are tracked via the Mcp-Session-Id request and response header.

Authentication

Send Authorization: Bearer sk-coco-… (or x-api-key) on every request. The key must have tools_enabled: true — otherwise the server returns 403 tools_disabled. See Authentication.

Session lifecycle

  1. Initialize. First request sets up a session.

    POST /v1/mcp HTTP/1.1
Authorization: Bearer sk-coco-…
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "vscode-copilot", "version": "1.95.0" }
  }
}

    The server responds with capabilities and Mcp-Session-Id in the response headers (cached for 1 hour in Redis).

  2. Subsequent calls must include Mcp-Session-Id: <id>. Calls without it on a non-initialize method return 404 Session not found or expired.

  3. Tool listing. tools/list returns the current catalog (see Reference → MCP tools).

  4. Tool calls. tools/call with the tool name and arguments. The server runs the tool against your connection (validating per-key scopes) and returns the result — possibly streaming.

  5. Close. Idle sessions expire after 1 hour. Clients can re-initialize at any time.

Available tools

ToolPurpose
sql_list_connectionsList the user’s connections (id, name, dialect, host, default DB).
sql_describeDescribe a table (columns, types, indexes, foreign keys).
sql_list_tablesList tables in a database/schema.
sql_runExecute a read-only SQL query. Server-side guard rejects DML/DDL by default.
sql_explainRun EXPLAIN on a query.
sql_historyRecent queries from the user’s history.

See Reference → MCP tools for full schemas, examples, and error semantics.

Examples

{
"mcp": {
  "cocobox": {
    "type": "remote",
    "url": "https://api.cocobox.io/v1/mcp",
    "headers": {
      "Authorization": "Bearer ${COCOBOX_API_KEY}"
    }
  }
}
}
{
"mcpServers": {
  "cocobox": {
    "type": "http",
    "url": "https://api.cocobox.io/v1/mcp",
    "headers": {
      "Authorization": "Bearer ${COCOBOX_API_KEY}"
    }
  }
}
}
{
"servers": {
  "cocobox": {
    "type": "http",
    "url": "https://api.cocobox.io/v1/mcp",
    "headers": {
      "Authorization": "Bearer ${env:COCOBOX_API_KEY}"
    }
  }
}
}
curl https://api.cocobox.io/v1/mcp \
-H "Authorization: Bearer $COCOBOX_API_KEY" \
-H "Content-Type: application/json" \
-i \
-d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "curl", "version": "8.4" }
  }
}'

Error envelope

Errors are returned as JSON-RPC 2.0 errors:

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params: connection_id is required" } }

HTTP-level errors (auth, missing session) use the standard Cocobox envelope:

{ "status": 403, "error": "tools_disabled", "message": "tools_enabled is false for this API key" }

What’s next