MCP Client — Using External MCP Servers

Sophon's MCP client consumes external MCP servers and bridges their tools into the agent registry. Once you register a server, its tools appear alongside Sophon's own — the agent doesn't distinguish "native" from "bridged."

Useful when a capability already exists as a well-maintained MCP server (filesystem, GitHub, Puppeteer, Notion, Slack, Linear) and you don't want to re-implement it as a Sophon skill.

Adding a server

From the Dashboard

Settings → MCP → Connections → Add Server. Pick a transport:

stdio — the most common for local / open-source MCP servers:

• Command — e.g., npx
• Args — e.g., ["-y", "@modelcontextprotocol/server-github"]
• Env — environment variables (e.g., API tokens, using {{vault:...}} references)

SSE or StreamableHTTP — remote MCP servers:

• URL — e.g., https://mcp.internal.example.com/sse
• Auth — None / API Key / Bearer / Basic
• Credentials — stored in the credential vault

Click Save, then Test. The client connects, negotiates capabilities, and enumerates tools + resources. Success → tools immediately appear in the agent registry.

From config

Edit ~/.sophon/config/mcp.json:

{
  "servers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "{{vault:github_mcp_pat}}"
      }
    }
  }
}

Changes are picked up live — no Gateway restart.

Tool visibility

By default, all tools from a connected server are visible to all agents. To restrict:

• Per-server exclusions — excludedTools: ["dangerous.wipe_disk"] in the server config.
• Per-agent allowlists — the same tool-registry allowlist that scopes Sophon's own tools also scopes bridged ones. Go to Agents → <agent> → Tools; bridged tools are labeled with the server name.

Collisions between servers (two servers both advertising a create_issue tool) are resolved by prefix: the bridged tools become github_mcp.create_issue and linear_mcp.create_issue. Tools that don't collide keep their original names.

Resources

Servers can expose read-only resources in addition to tools. The Dashboard's Connections tab lists them; agents can reference resources in prompts via the resource.read tool:

resource.read(uri: "github://repos/acme/core/issues/123")

This is how, for example, a GitHub MCP server lets the agent read issue text without you having to upload the issue to documents first.

Authentication to external servers

stdio servers

Secrets go into the env block of the server config, pulling from the credential vault with {{vault:...}}:

{
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "{{vault:github_mcp_pat}}",
    "GITHUB_API_URL": "https://api.github.com"
  }
}

Set up the vault entry first — Settings → Connections → Add with type Generic API Key.

Remote (SSE / HTTP) servers

Pick an auth scheme in the server setup:

• API Key — sends as X-API-Key header
• Bearer — sends as Authorization: Bearer <token>
• Custom header — any header name

The token is stored in the vault and injected on each request. It's never logged.

Timeouts and retries

• Per-call timeout: 30 seconds (configurable per server).
• On timeout or 5xx response, the client retries up to 3 times with exponential backoff.
• Persistent failures mark the server as Unhealthy in the Dashboard; agents see tools from that server fail with a clear error ("MCP server github is unhealthy").
• Auto-reconnect — if a stdio subprocess exits or an SSE connection drops, Sophon respawns / reconnects with exponential backoff.

Observability

Every MCP tool call is logged with:

• Server, tool name, arguments (redacted for sensitive params)
• Response status, duration
• Retry count, final error (if any)

Dashboard → Settings → MCP → Connections → <server> → Activity shows the last 100 calls.

Example — GitHub MCP server

{
  "servers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "{{vault:github_mcp_pat}}"
      },
      "excludedTools": [],
      "description": "Read/write GitHub issues, PRs, and repos"
    }
  }
}

After connecting, tools like search_repositories, create_issue, get_file_contents, get_pull_request appear in the agent registry (prefixed github.* or similar depending on the server's advertised naming).

Example — Filesystem MCP server

{
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/projects"
      ],
      "description": "Read/write files under ~/projects"
    }
  }
}

The filesystem server is scoped to the directory you pass. Great for local development agents.

Approval integration

Bridged MCP tools inherit the same risk-level system as native tools. If a server advertises a tool as destructive, Sophon gates it through the approval middleware. If a server doesn't declare risk levels, Sophon defaults to Medium and you can override in the Excluded / Risk overrides panel.

CLI

sophon mcp servers               # list external servers
sophon mcp add <name> --stdio --cmd "npx -y @mcp/github"
sophon mcp add <name> --sse --url https://example.com/mcp
sophon mcp test <name>           # connect, enumerate, disconnect
sophon mcp tools <name>          # list tools from a server
sophon mcp remove <name>

Limits and gotchas

• stdio subprocess lifetime — the subprocess runs as long as Sophon. If it's a chatty process, watch the logs for issues. excludedTools trim what's bridged but not what the subprocess does internally.
• SSE through proxies — if your SSE endpoint is behind a proxy with aggressive idle timeouts, the connection may drop. Set the proxy proxy_read_timeout ≥ 5 minutes and Sophon will reconnect on drops.
• Resource URIs — some servers don't expose resources, only tools. That's fine; you just won't see them in the Resources list.
• Schema validation — Sophon validates tool input against the server's advertised JSON Schema. Malformed arguments return a clear error before the call is made.

Where to go next

• MCP Overview — the protocol and transports
• MCP Server — exposing Sophon's tools to external clients
• Connections — storing external server credentials in the vault