Skip to main content

MCP Servers

Every tool your agent calls beyond the platform's own — GitHub, a browser, an internal API — comes from an MCP server. The gateway discovers each configured server's tools and exposes them at SYPHO_MCP_URL, named mcp__<server-name>__<tool-name>; your manifest's tools/deny_tools then authorize which of them this agent may actually call. See Tool patterns for the allow/deny syntax.

This page is about MCP servers your agents call at run time. For operating the platform itself from an MCP client like Claude Code, see AI Assistant Access.

There are two ways a server gets there.

Managed and remote MCP servers​

Registered centrally — not per manifest — at an organization or application scope, by name and URL. Any manifest in that scope can reference its tools immediately:

{
  "tools": ["mcp__github__*"]
}

Nothing else to declare: no custom_mcps entry, no credentials in the manifest. Auth (if the server needs it) is resolved by server name when the run starts, never carried in the manifest itself. Register one from the dashboard or POST /mcp-servers.

Custom MCP servers​

When the tool you need isn't a managed server, declare your own — sandboxed and run alongside the agent for the lifetime of the run:

{
  "custom_mcps": [
    {
      "name": "internal-crm",
      "source": { "type": "git", "url": "git@github.com:acme/crm-mcp.git", "ref": "v1.4.0", "subdirectory": "server" },
      "entrypoint": "crm-mcp",
      "env": { "CRM_API_KEY": "Sypho<crm_api_key>" },
      "resources": { "timeout_ms": 10000, "call_timeout_ms": 30000 }
    }
  ],
  "tools": ["mcp__internal-crm__*"]
}
  • name — how tools entries reference it: mcp__internal-crm__*, same convention as managed/remote MCPs.
  • source — where the server's code comes from:
    • git — a Python package run via uvx; subdirectory points at the package's path inside the repo when it isn't the repo root.
    • codeartifact — a private Python package via CodeArtifact, run via uvx.
    • npm — a published Node package run via npx (no separate entrypoint needed — npx invokes the package's own bin).
  • entrypoint — the console-script name uvx invokes (git/codeartifact sources only).
  • env — environment for the sandboxed MCP process. Each value is either a literal, or "Sypho<alias>" to resolve a secret your manifest declares under secrets — the real value is injected at startup and never stored on the run.
  • resources.timeout_ms — how long the MCP may take to start.
  • resources.call_timeout_ms — how long one tool call may take (default: the MCP SDK's 60s) — raise this for a tool that waits on a human, for example.