Skip to main content

CAD041: Model Context Protocol (MCP)

Overview​

This CAD describes the Convex implementation of the Model Context Protocol (MCP), a standardised protocol that enables AI agents to discover, understand, and invoke tools — including executing economically significant operations — through a structured interface.

MCP provides a universal language for AI agents to interact with Convex, allowing them to query data, execute transactions, manage digital assets, and receive real-time state change notifications without requiring custom integrations.

/mcp Endpoint​

Convex peers MAY implement MCP endpoint support through a dedicated /mcp endpoint that exposes Convex network capabilities to AI agents and other MCP-compatible clients.

The endpoint supports three HTTP methods:

  • POST /mcp — JSON-RPC requests (tools, prompts, queries, transactions). Supports both standard JSON responses and Server-Sent Events (SSE) streaming when the client sends Accept: text/event-stream.
  • GET /mcp — Opens an SSE stream for receiving asynchronous notifications (state change events, keep-alive pings). Requires a valid Mcp-Session-Id header.
  • DELETE /mcp — Terminates a session and cleans up associated resources (watches, connections).

A discovery document is published at /.well-known/mcp for auto-detection by MCP clients.

Protocol Version​

The Convex MCP server implements MCP specification version 2025-11-25 with the Streamable HTTP transport.

On initialize, the server negotiates the protocol version with the client: if the client requests a version the server supports (currently 2025-11-25, 2025-06-18, or 2025-03-26), the server echoes that version back. Otherwise the server responds with its latest supported version and the client decides whether to proceed. This keeps older MCP clients working whilst allowing newer clients to use the latest spec features.

Sessions​

Stateful sessions are created on initialize and identified by the Mcp-Session-Id response header. Sessions track:

  • SSE connections for notification delivery
  • State watches registered via watchState
  • Session-scoped resources

Sessions are terminated explicitly via DELETE /mcp or cleaned up on connection timeout.

Tools​

The MCP server exposes tools organised into categories. Clients discover available tools via tools/list. The full set depends on whether the peer's signing service is configured.

Core tools (always available)​

22 tools covering queries, transactions, cryptography, encoding, and state watching:

  • Queries and state — query (execute Convex Lisp), queryState (navigate the global state tree), describeAccount, getBalance, lookup, resolveCNS, peerStatus, getTransaction
  • Transactions — transact (direct execution with seed), prepare / submit (two-step with external signing), signAndSubmit, transfer (convenience for coin/token transfers)
  • Accounts — createAccount (with optional faucet funding)
  • Cryptography — keyGen, sign, validate, hash (Ed25519 and SHA-256/SHA3)
  • Encoding — encode / decode (CVM literals ↔ CAD3 binary)
  • State watching — watchState / unwatchState (register watches on state paths; changes delivered as SSE notifications)

Signing service tools (conditional)​

When a peer is configured with a signing service, 13 additional tools are registered for server-side key management. Private keys are stored encrypted and never leave the server.

  • Key management — signingCreateKey, signingListKeys, signingSign, signingGetJWT
  • Convenience — signingTransact (execute using a stored key), signingCreateAccount, signingListAccounts
  • Delegation — signingDelegate (issue a UCAN delegation token signed by a stored key, without exposing the key)
  • Elevated — signingImportKey, signingExportKey, signingDeleteKey, signingChangePassphrase — these require a two-step browser confirmation flow to prevent programmatic abuse
  • Discovery — signingServiceInfo (check availability, no authentication required)

Prompts​

The MCP server exposes guided workflow prompts via prompts/list and prompts/get. Prompts are user-controlled templates (triggered by slash commands or explicit selection) that guide LLMs through multi-step tasks using available tools.

Each prompt follows a three-message pattern: a persona message that teaches the LLM relevant Convex domain knowledge, a request message with ${argName} placeholders substituted from user-supplied arguments, and an assistant prefill that anchors the response direction.

Some prompts are always available (e.g. account exploration, network status, Convex Lisp guidance); others are registered only when the signing service is configured (e.g. account creation, contract deployment, fund transfers).

Server-Sent Events (SSE)​

The MCP server supports real-time notifications via SSE for state watching. When a client registers a watch with watchState, the server monitors the specified path in the global CVM state and sends notifications/stateChanged events over the SSE stream whenever the value changes.

SSE is also used for streaming responses on POST when the client includes Accept: text/event-stream.

Extensibility​

The McpServer base class is designed for extension. Subclasses can override protected methods to customise tool discovery, tool dispatch, and protocol negotiation:

MethodPurpose
buildInitializeResult(params)Customise the initialize response (capabilities, server info)
listTools()Return a custom set of available tools
toolCall(params)Dispatch tool calls with custom logic
handlePost(ctx)Override full POST request handling
createResponse(id, result)Customise JSON-RPC response construction

This enables:

  • Adapter-based tool discovery — dynamically register tools from loaded adapters (used by Covia venues)
  • Custom tool dispatch — route tool calls to domain-specific handlers
  • Protocol extensions — add custom JSON-RPC methods beyond the MCP specification
  • Batch request handling — the base implementation supports up to 20 requests per batch

Tool Registration​

External modules register tools via the tool registry:

mcpServer.registerTool("my-tool", schema, handler);

Registered tools appear in tools/list responses and are dispatched by toolCall().

Security Considerations​

  • Seed-based tools (transact, signAndSubmit, transfer) transmit the Ed25519 seed over the network — peers MUST use HTTPS
  • Signing service tools keep private keys server-side, encrypted at rest with a user-chosen passphrase
  • Elevated operations (import, export, delete) require interactive browser confirmation to prevent programmatic abuse
  • Queries are read-only and require no authentication
  • Sessions are server-side and scoped to a single client connection

Reference Implementations​

  • Server — convex-restapi ships the /mcp endpoint as part of every Convex peer, covering the full tool and prompt set described above.
  • Claude Code plugin — Convex-Dev/convex-plugin is a one-line install that binds the peer's MCP endpoint, injects Convex terminology and tool-selection guidance, and ships convenience slash commands (/convex:faucet, /convex:explore) along with a Convex-Lisp-aware subagent.

References​