Reference

MCP servers

Connect external Model Context Protocol (MCP) servers to extend your agents' toolkit. SyftOS acts as an MCP client: it discovers each server's tools, you risk-classify them, and from then on they flow through the same approval gate, guardrails and audit as a native tool.

What it's for

An MCP server is an external system that publishes a set of tools over the Model Context Protocol. Connecting one lets your agents call those tools without you having to build a custom tool by hand.

The catalogue lists every connected server with its status, how many of its tools are classified (and therefore assignable), and a needs classification badge that surfaces outstanding work. Each server is namespaced by a short slug, so its tools appear in the registry as mcp.{slug}.{tool}.

Connecting a server

Choose Connect a server and complete the guided form:

• Name: a human-readable label for the connection.
• Namespace: a short slug (2–24 characters, lower-case letters, digits and underscores), unique within your organisation. It is folded into every tool's registry slug.
• Endpoint: the server's https URL. It is screened against SyftOS's SSRF guard, so endpoints that resolve to blocked or private addresses are rejected.
• Auth: an API key or OAuth token (a bearer token), sent as an Authorization header on every call.

Before anything is stored, SyftOS screens the endpoint and runs the MCP initialize handshake with your supplied token. An invalid endpoint or token never reaches the vault — you'll see the error on the form instead. Once it passes, the connection is created, its tools are discovered (recorded unclassified), and you're taken to the connection detail page to review them.

Discovering and reclassifying tools

Discovery reads the tool list the server advertises. If discovery hiccups during connect, the connection still goes live and you can re-run it with Rediscover on the connection page.

Rediscovering an already-connected server reconciles the tool list:

• New tools are recorded unclassified and need classifying before agents can use them.
• Existing classified tools keep their classification; their metadata (name, description, server hints) is refreshed.
• Tools that have vanished from the server are marked unavailable.

You can only rediscover a usable connection — if the server has been disconnected, reconnect it first.

Classifying a tool's risk

Classification is the act that makes a discovered tool assignable. For each tool you must record two mandatory fields, mirroring the rule for native tools:

• Side effect: whether the tool changes external state. Side-effecting calls become gated agent actions.
• Risk level: low, medium or high. Risk-based approval policies may auto-approve low and medium, but high is never auto-approvable.

The server may declare its own annotation hints (for example read-only or destructive). These are shown to inform your decision but are never trusted in place of it. Where the server gives no hint, SyftOS pre-selects the fail-safe default: high risk and side-effecting. Classifying a tool creates or updates a registry row in your organisation's tools, so it now behaves exactly like a native tool.

Governance, audit and disconnecting

The entire surface (viewing, connecting, discovering, classifying and disconnecting) is gated by the integrations.manage permission, held by owners and admins only. MCP servers are external systems, so they sit at the same trust level as other integrations. Every connection and its tools are scoped to your organisation; another organisation's connection or tool resolves as a 404.

Because classification routes MCP-backed calls through the standard pipeline, every side-effecting action goes through the Approval Centre and is recorded in the audit log. The connection detail page also shows the recent audit history for that connection.

Disconnecting forgets the server's credentials and retires its tools. They're disabled, never deleted, so historical actions that referenced them stay intact. Reconnecting and rediscovering brings the tools back, but they stay disabled until you reclassify each one's risk level. Classification is what makes a tool assignable again.

Next steps