MCP Server — Exposing Sophon Tools

Sophon includes a full MCP server. Enable it, pick transports, mint Bearer tokens, and external AI clients can invoke Sophon's tools (memory.search, workflow.trigger, document.query, …) and read Sophon's resources (documents, memory entries, agent files).

This turns Sophon into a hub: clients (Claude Desktop, Cursor, your own agent) can query it for memory and documents, trigger workflows, or chain Sophon's tools into their own agent loops.

Enabling the server

Dashboard → Settings → MCP → Server. Toggle Enabled. Pick transports:

• stdio — for local CLI-style clients (Claude Desktop's native MCP config reads from stdio)
• SSE — for remote streaming clients
• StreamableHTTP — for remote request/response clients

Or edit ~/.sophon/config/mcp-server.json:

{
  "enabled": true,
  "transports": {
    "stdio": { "enabled": true },
    "sse": { "enabled": true, "path": "/mcp/sse" },
    "streamableHttp": { "enabled": true, "path": "/mcp/http" }
  },
  "auth": {
    "tokens": [
      { "id": "claude-desktop", "token": "{{vault:mcp_claude_token}}" }
    ]
  },
  "expose": {
    "tools": ["memory.*", "document.*", "workflow.list", "workflow.trigger", "insights.query"],
    "resources": ["documents/*", "memory/*", "agents/*"]
  }
}

Transport endpoints

For stdio, give the client this command in its own MCP config:

{
  "mcpServers": {
    "sophon": {
      "command": "sophon",
      "args": ["mcp", "serve", "--stdio"],
      "env": { "SOPHON_GATEWAY": "http://localhost:8080" }
    }
  }
}

Authentication

stdio has no network boundary — the auth is your shell identity.

SSE and StreamableHTTP require Bearer tokens. Generate one per client:

Dashboard → Settings → MCP → Server → Tokens → Generate. Give the token a label (e.g., claude-desktop). Copy it once; it's not stored in clear text afterwards.

Clients send Authorization: Bearer <token> on every request. Unauthenticated requests are rejected with 401.

Rotate a token by regenerating; the old one is invalidated immediately.

What's exposed by default

Tools

By default, Sophon exposes a safe subset:

• memory.search, memory.list, memory.get, memory.traverse (read-only)
• document.search, document.get, document.summarize (read-only)
• workflow.list, workflow.describe, workflow.trigger (trigger requires user to have trusted the workflow)
• insights.query (user's own analytics)
• task.list, task.describe (read-only)

Not exposed by default: anything that writes memory, modifies workflows, sends email, executes shell commands, configures connections. You can opt-in via expose.tools if you trust the connecting client — but do it deliberately.

Resources

By default, read-only URIs:

• sophon://documents/{id} — an extracted document's text
• sophon://documents/ — list of documents accessible to the user
• sophon://memory/{id} — a single memory entry
• sophon://agents/{id}/SOUL.md — an agent's personality file

Resources are user-scoped. If user A's token queries sophon://documents/xyz but that document belongs to user B, the server returns 404.

Claude Desktop example

Once Sophon's stdio MCP server is enabled, add this to Claude Desktop's MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "sophon": {
      "command": "sophon",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

Restart Claude Desktop. You'll see Sophon's tools listed in Claude's tool picker. Claude can now search your Sophon memory, query your documents, and list workflows as part of its own reasoning.

Cursor example

Cursor speaks StreamableHTTP. Add Sophon to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "sophon": {
      "url": "http://localhost:8080/mcp/http",
      "headers": {
        "Authorization": "Bearer sk_cursor_abc123..."
      }
    }
  }
}

Restart Cursor. Sophon's tools are available inside Cursor's agent panel.

Monitoring connected clients

Dashboard → Settings → MCP → Server → Connections lists live clients, their transport, their token ID, last request, and total call count. Disconnect a client by revoking its token.

Observability

Every inbound MCP call is logged with:

• Client token ID, tool / resource name, arguments (redacted for sensitive args)
• User identity (mapped from the token)
• Response status, duration

This is the same audit log that covers REST and SignalR calls. Enterprise audit streams include MCP activity.

Limits

• stdio is single-client — Sophon can only have one stdio connection at a time (tied to the subprocess). For multiple clients, use SSE / HTTP.
• Per-token rate limit — 60 calls/minute. Busier clients need a higher limit per token (configurable).
• Max payload — 5 MB request, 10 MB response. Truncation applies to large tool results (same 8000-char truncator that Sophon's native pipeline uses).
• Token lifetime — tokens don't expire by default. Rotate quarterly or on employee turnover.

Security considerations

• Only expose what you trust. The default allowlist is conservative for a reason. Opening memory.write or connection.configure to an external client gives that client write access to your memory and credentials.
• Never share tokens across clients. Each client gets its own token so you can audit and revoke independently.
• TLS in front of SSE/HTTP in production. Don't expose /mcp/* over plain HTTP except on localhost.
• SSRF concerns don't apply on the server side — clients call into Sophon, not the other way around. But if your MCP server is behind a corporate proxy, make sure the proxy passes the Authorization header.

CLI

sophon mcp serve --stdio           # run the stdio server
sophon mcp tokens list
sophon mcp tokens create --label cursor
sophon mcp tokens revoke <token-id>
sophon mcp clients                 # who's connected right now

Where to go next

• MCP Overview — the protocol and role architecture
• MCP Client — consume external MCP servers from Sophon
• API Reference — MCP — JSON-RPC method list