MCP — Overview

Sophon as an MCP client and server — connect to external MCP tool providers, and expose Sophon's tools to external AI clients.

The Model Context Protocol (MCP) is a JSON-RPC standard for AI systems to discover and invoke tools. Sophon speaks it in both directions:

As an MCP client, Sophon connects to external MCP servers (GitHub's, Linear's, a Filesystem server, your own) and merges their tools into the agent registry. The agent can invoke them as if they were native Sophon tools.
As an MCP server, Sophon exposes its own tools (memory, workflows, documents, skills) and resources to external MCP clients — Claude Desktop, Cursor, your own agents.

You can use both simultaneously. A typical Sophon deployment acts as a hub: it consumes external MCP tools, wraps them in its own orchestration / approval / budget layer, and re-exposes them (plus its native features) to downstream clients.

The two roles

┌───────────────────────────────────────────────────────────────┐
│                                                               │
│   External MCP servers                       External clients │
│   (GitHub, Filesystem, Linear, …)            (Claude Desktop, │
│            │                                  Cursor, custom) │
│            │ JSON-RPC                                 │       │
│            ▼                                          │       │
│     ┌─────────────┐                                   │       │
│     │  Sophon     │  ◀──────────────────────────── JSON-RPC   │
│     │  (client)   │                                           │
│     │             │                                           │
│     │  (server)   │ ◀──── tools + resources                   │
│     └─────────────┘                                           │
│                                                               │
└───────────────────────────────────────────────────────────────┘

Transports

MCP traffic moves over one of three transports:

Transport	Use case	Pros	Cons
stdio	Local CLI-style integrations, Claude Desktop	Zero network config, subprocess lifecycle is simple	Single-client only, bound to Gateway host
SSE (Server-Sent Events)	Remote clients, long-lived streaming	Works through proxies, firewalls, browsers	One-way server push (clients POST separately)
StreamableHTTP	Remote clients, request/response	Stateless HTTP, easy to operate	No server-initiated notifications

Sophon's MCP server can expose any / all transports simultaneously. The MCP client picks a transport based on the external server's advertised options.

Authentication

stdio has no network boundary — auth is implicit (the subprocess inherits the user's identity).
SSE / StreamableHTTP use Bearer tokens. For servers, Sophon generates tokens per-client; for clients connecting to external servers, you paste the external server's token during setup.
Some external servers use API keys instead of Bearer tokens; Sophon supports both patterns.

Configuration files

Two JSON files in ~/.sophon/config/:

`mcp.json` — client configuration

Lists external MCP servers Sophon connects to:

{
  "servers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "{{vault:github_pat}}" }
    },
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "internal-api": {
      "transport": "sse",
      "url": "https://mcp.internal.company.com/sse",
      "auth": { "type": "bearer", "token": "{{vault:internal_mcp_token}}" }
    }
  }
}

{{vault:...}} references pull from the credential vault, so raw tokens aren't in this file.

`mcp-server.json` — server configuration

Governs how Sophon's own MCP server behaves:

{
  "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}}" },
      { "id": "cursor", "token": "{{vault:mcp_cursor_token}}" }
    ]
  },
  "expose": {
    "tools": ["memory.*", "document.*", "workflow.list", "insights.query"],
    "resources": ["documents/*", "memory/*"]
  }
}

expose.tools is an allowlist — only matched tools are visible to MCP clients. Critical tools (shell execution, credential configure) are excluded by default.

Tool and resource model

Tools — callable actions. In Sophon's registry they have names like memory.search; the MCP server re-exports them with the same name. External MCP servers may advertise tools with any name; Sophon bridges them in under their advertised names (or with a prefix if there's a collision — e.g., github_mcp.create_issue).

Resources — named, readable pieces of content. Sophon exposes documents, memory entries, and agent files as resources with URIs like:

sophon://documents/{id} — an extracted document
sophon://memory/{id} — a single memory entry
sophon://agents/{id}/SOUL.md — an agent's personality file

External MCP clients can list and read resources — e.g., Claude Desktop can ask Sophon for a document's text and include it in its own context.

What the Dashboard shows

Settings → MCP has two tabs:

Connections — external servers Sophon connects to. Status (connected / error / disconnected), tool count, last heartbeat, exclusion list.
Server — Sophon's own MCP server configuration. Enable transports, generate tokens, set allowlists. Live status of connected clients.

Where to go next

MCP Client — using external MCP servers from Sophon
MCP Server — exposing Sophon to external AI clients
MCP API Reference — JSON-RPC method surface

MCP — Overview

On this page