Surface docsProtocol
For building your own client — the endpoint, headers, methods and status codes.
Clients like Claude Code handle all of this. Read on if you're calling the server directly.
JSON-RPC over POST https://mcp.surface-ai.io/mcp/, JSON responses only, no sessions. Each request
sends Mcp-Method and MCP-Protocol-Version headers that must match the body, and a _meta with
the protocol version and client capabilities.
curl -s https://mcp.surface-ai.io/mcp/ \
-H "Authorization: Bearer $SURFACE_MANAGEMENT_KEY" \
-H 'Content-Type: application/json' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: tools/list' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{
"io.modelcontextprotocol/protocolVersion":"2026-07-28",
"io.modelcontextprotocol/clientCapabilities":{}}}}'Methods
| Method | Purpose |
|---|---|
server/discover | Supported versions, capabilities and server identity. |
tools/list | The ten tools with their input schemas. Cacheable for an hour. |
tools/call | Run a tool: params { name, arguments }. |
resources/list | Always empty — surfaces are reached by template. |
resources/templates/list | surface://{surface_id} |
resources/read | Read surface://<id> as JSON. |
prompts/list | setup_surface — in Claude Code, /mcp__surface__setup_surface. |
prompts/get | The setup workflow, with an optional page argument. |
HTTP status codes
| Status | When |
|---|---|
200 | Success — including a tool that failed, which returns isError: true. |
400 | Bad JSON, a header that disagrees with the body, or an unsupported protocol version (the error lists 2026-07-28). |
401 | Missing, unknown or revoked key. |
403 | An Origin header from a host we don't serve. |
404 | A method the server doesn't implement, such as initialize. |
405 | GET or DELETE on /mcp/. |