MCP API

JSON-RPC method surface Sophon exposes as an MCP server — tool catalog, resource URIs, auth headers.

Sophon's MCP server implements the Model Context Protocol JSON-RPC surface. This page is the wire-level reference for clients that want to call Sophon as an MCP server — for the user-facing setup flow see MCP Server.

Transports

Transport	Endpoint	Framing
stdio	`sophon mcp serve --stdio`	newline-delimited JSON-RPC 2.0
SSE	`GET /mcp/sse`, POSTs to `/mcp/sse/message`	SSE events for server push, POST for client messages
StreamableHTTP	`POST /mcp/http`	Single request / response JSON-RPC

Authentication

stdio

Inherits the user's shell identity; no additional auth.

SSE and HTTP

Authorization: Bearer <token> on every request. Tokens are generated in Settings → MCP → Server → Tokens.

Unauthenticated requests return JSON-RPC error -32600 with HTTP status 401.

Protocol

MCP over JSON-RPC 2.0. Requests:

{
  "jsonrpc": "2.0",
  "id": "<client-generated>",
  "method": "tools/list",
  "params": {}
}

Responses:

{
  "jsonrpc": "2.0",
  "id": "<echoed>",
  "result": { ... }
}

Initialization

First message in any session is initialize:

{
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": { "name": "claude-desktop", "version": "0.7.2" },
    "capabilities": {}
  }
}

Response:

{
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": { "name": "sophon", "version": "1.0.0" },
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "listChanged": true, "subscribe": true },
      "prompts": { "listChanged": true }
    }
  }
}

After initialize, the client sends notifications/initialized (no response expected).

Tools

`tools/list`

{ "method": "tools/list", "params": {} }

Returns allowed tools for the authenticated user, filtered by the server's expose.tools allowlist (see MCP Server).

{
  "result": {
    "tools": [
      {
        "name": "memory.search",
        "description": "Search user and agent memory by natural-language query.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string" },
            "scope": { "type": "string", "enum": ["user", "agent", "all"] },
            "limit": { "type": "integer", "minimum": 1, "maximum": 100 }
          },
          "required": ["query"]
        }
      }
    ]
  }
}

`tools/call`

{
  "method": "tools/call",
  "params": {
    "name": "memory.search",
    "arguments": { "query": "project deadline", "limit": 5 }
  }
}

Response:

{
  "result": {
    "content": [
      { "type": "text", "text": "Found 3 entries: ..." }
    ],
    "isError": false
  }
}

Tool calls enforce the same risk-level / approval gate as internal invocations. If a tool is ≥ High risk, tools/call may block while an approval is resolved on Dashboard / mobile; timeout returns isError: true.

`notifications/tools/list_changed`

Server-initiated when the allowlist changes.

Resources

`resources/list`

{ "method": "resources/list", "params": {} }

{
  "result": {
    "resources": [
      {
        "uri": "sophon://documents/doc_abc123",
        "name": "Q3-sales-report.pdf",
        "description": "Q3 sales report — uploaded 2026-04-15",
        "mimeType": "application/pdf"
      },
      {
        "uri": "sophon://memory/mem_xyz789",
        "name": "User preference: dark mode",
        "description": "Long-term preference entry",
        "mimeType": "text/plain"
      }
    ]
  }
}

Resources are user-scoped; only items the authenticated token's user can access are returned.

`resources/read`

{
  "method": "resources/read",
  "params": { "uri": "sophon://documents/doc_abc123" }
}

Response:

{
  "result": {
    "contents": [
      {
        "uri": "sophon://documents/doc_abc123",
        "mimeType": "text/plain",
        "text": "<full extracted text of the document>"
      }
    ]
  }
}

For binary resources, contents[].blob is base64-encoded and mimeType is the original content type.

`resources/subscribe`, `resources/unsubscribe`

For clients that want to be notified when a specific resource changes. Sophon emits notifications/resources/updated when a subscribed resource is modified.

URI schemes

Scheme	Examples
`sophon://documents/{id}`	Extracted text of a document
`sophon://documents/`	List (plus catalog)
`sophon://memory/{id}`	A memory entry
`sophon://memory/`	User-accessible memory listing
`sophon://agents/{id}/SOUL.md`	Agent personality file
`sophon://agents/{id}/config`	Agent configuration JSON
`sophon://workflows/{id}`	Workflow JSON

Prompts

MCP supports server-provided prompt templates. Sophon exposes a small set of curated prompts:

`prompts/list`

{ "method": "prompts/list", "params": {} }

Response includes:

summarize-document — summarize a Sophon document
draft-email — draft an email based on context
extract-action-items — pull action items from a meeting transcript
research-topic — multi-source research prompt

`prompts/get`

{
  "method": "prompts/get",
  "params": {
    "name": "summarize-document",
    "arguments": { "documentUri": "sophon://documents/doc_abc" }
  }
}

Returns a rendered prompt with the document's text substituted in.

Errors

JSON-RPC error shape:

{
  "jsonrpc": "2.0",
  "id": "<echoed>",
  "error": {
    "code": -32602,
    "message": "Invalid params: 'query' is required"
  }
}

Sophon-specific error codes (beyond standard JSON-RPC):

Code	Meaning
`-32700`	Parse error
`-32600`	Invalid request (auth, schema)
`-32601`	Method not found
`-32602`	Invalid params
`-32603`	Internal error
`-32000`	Tool not in allowlist
`-32001`	Approval rejected
`-32002`	Approval timed out
`-32003`	Budget exceeded
`-32004`	Rate limit exceeded

MCP Server — user-facing setup
MCP Client — consume external MCP servers
Upstream spec: Model Context Protocol

Transports

Authentication

stdio

SSE and HTTP

Protocol

Initialization

Tools

`tools/list`

`tools/call`

`notifications/tools/list_changed`

Resources

`resources/list`

`resources/read`

`resources/subscribe`, `resources/unsubscribe`

URI schemes

Prompts

`prompts/list`

`prompts/get`

Errors

Rate limits

Logging

Where to go next

On this page