Tools and connections

MCP

Give agents tools from Model Context Protocol servers, and reach your own agents from any MCP client.

The Model Context Protocol (MCP) is an open way for an AI application to discover and call tools. Snaga uses it in both directions:

Agents use MCP servers. Connect a vendor's MCP server — or your own — and its tools become available to the agents you choose.
Snaga is an MCP server. An MCP client can connect to the platform and talk to one of your agents: start a run, check on it, read its memory.

Agents using MCP servers

Install, then connect

Managing the company's MCP servers needs the developer role or higher on every method, plus a key with agents:read to read and agents:write for anything that changes them.

Two steps, and the second one is the one people forget. A server is installed for the whole company, then connected to agents. A server connected to nobody reaches nobody: its tools appear for no agent.

The one-step catalog

The quickest route is the catalog of vendor-hosted servers (Stripe, Notion, Attio, Linear and others):

curl https://api.snaga.ai/api/v1/mcp/catalog \
  -H "Authorization: Bearer $SNAGA_API_KEY"

Each entry says whether it needs a sign-in (auth: oauth) or is public (auth: none), whether it can only read or also write (access), and which risks its tools carry — money, send or delete, the things that cannot be taken back. Where a vendor offers a read-only endpoint it is listed as read_only_url.

Connect an entry, or any streamable-HTTP MCP server by URL, with:

curl -X POST https://api.snaga.ai/api/v1/mcp/connect \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"catalog_id": "<catalog_id>", "agent_ids": ["<agent_id>"]}'

Send exactly one of catalog_id and url. What comes back depends on the server:

No sign-in needed — 201, status: connected. The server is stored, its live session opened, and tools lists what it offers.
Sign-in needed — status: authorization_required with an authorize_url. Open it in a browser; after the person signs in at the vendor, the browser returns to the web app, which finishes with POST /api/v1/mcp/oauth/complete. A started connection is forgotten after 10 minutes, and only the person who started it can finish it.
Already connected — 200 with already_connected: true; the agents are added to the existing server rather than connecting it twice.

For sign-in, the platform registers itself with the vendor's authorization server, uses PKCE (S256) and binds the token to that one server. When a grant expires or you want to switch the vendor account behind it, POST /api/v1/mcp/servers/{serverId}/reconnect starts a fresh sign-in and keeps the same server record and agents.

Registering a server by hand

POST /api/v1/mcp/servers registers a server with full control: name and transport (http or streamable_http; stdio is refused on production unless the host opts in) are required, plus a url. The URL is checked before anything is stored — a hostname that resolves to a private or metadata address is refused.

Put a server's secret in env and say where it goes with auth (type: api_key, the header, an optional prefix). env is encrypted at rest and never returned; reads show only env_count. Pass assigned_agent_ids in the same call so the server is connected at once.

A save that could not open a live session still succeeds, and says why in connect_error — check it.

Choosing which agents see a server

curl -X PUT https://api.snaga.ai/api/v1/agents/<agent_id>/mcp-servers \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_ids": ["<server_id>"]}'

The array is this agent's complete set; [] disconnects everything. Other agents' connections are untouched. An id the company does not have is refused with 422 and nothing is written. GET on the same path lists the servers the agent is connected to.

Checking a server

POST /api/v1/mcp/servers/{serverId}/test opens a real connection and lists the server's tools. A failed probe is still 200 — read ok. On false, error says why.

Moving a server to a different origin while it holds a stored secret is refused with 409 (secret_would_move) unless the same request says what the secret is at the new address. Deleting a server answers with how many agents still name it, so you can see the reach of the change.

Snaga as an MCP server

The platform exposes an MCP endpoint at https://api.snaga.ai/api/v1/mcp (Streamable HTTP: POST carries JSON-RPC 2.0, GET is the stream half). Each request is stateless; no Mcp-Session-Id is issued.

Authenticate with your API key (scope agents:read) and, optionally, name the agent you want to speak to in X-UARP-Agent-Id. Without that header the call goes to your company's head agent, the Chief of Staff. Only when there is no head agent either does the endpoint answer 400, with a JSON-RPC error envelope (code -32600).

curl -X POST https://api.snaga.ai/api/v1/mcp \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "X-UARP-Agent-Id: <agent_id>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

What an MCP client gets for that agent:

Kind	What
Tools	`invoke_agent` (start a run), `get_run_status`, `cancel_run`, `query_memory`
Resources	the agent's configuration (read-only), its memory, the company's knowledge bases
Prompts	the agent's system prompt and its skills

Starting a run needs agents:write on the key, and counts against your run allowance like any other run. Memory and knowledge bases are listed only when the key may read them. A key that lacks the role or scope is refused as a JSON-RPC error (code -32001, HTTP 403), because MCP clients cannot read the platform's usual error body. A request with no key at all is stopped earlier and gets the ordinary 401 problem document.

Integrations — OAuth connectors managed by the platform.
Chief of Staff — the head agent MCP falls back to.
Memory and knowledge — what the MCP resources expose.

MCP