Connect MCP servers

An MCP server is a remote service that offers tools over the Model Context Protocol. When you add one to an agent, each session connects to the server, discovers its tools, and lets the agent call them. Calls are made outside the sandbox, and vault credentials are attached to those requests and masked from returned text and structured data before the agent sees them. This page covers agents calling out to MCP servers. To connect your coding assistant to these docs or to the Managed Agents MCP endpoint, see Use with AI coding agents.

Changing an agent or testing a server needs the organization developer or admin role. Testing a server needs the create permission, so the organization user role can’t run a test. See Organizations and roles. The server must use the Streamable HTTP transport at a public http or https URL. Servers on private, loopback, or link-local addresses are refused. Local servers that run over stdio aren’t supported. If the server needs a token, have it ready; the token goes in a vault.

If the service is one of the 164+ apps in Integrations, you can connect it there instead and choose its tools, without handling a token.

About the Managed Agents MCP endpoint

On the Managed Agents MCP endpoint, operation arguments name path parameters in camelCase, such as vaultId, while request bodies keep their snake_case fields, such as vault_id. Create skills with scripts, and read a skill version’s content, in the console or with the REST API.

Add an MCP server to an agent

Each server entry has a name and a url. MCP servers belong to the agent version, so adding one creates a new version. Running sessions keep the tools they have until you move them to the new version.

Console
cURL

In the sidebar, click Agents and open the agent.
On Configuration, find Tools and click Add custom MCP server.
Choose a server from the list or paste its URL. The list suggests a few common servers and says what kind of token each needs. A server from the list is named for you; any other server is named after its URL.
Click Save new version.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v2/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/versions' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "baseAgentVersionId": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21",
    "name": "Release coordinator",
    "model": "<model-id>",
    "system": "Track the release and report blocked work.",
    "mcpServers": [{"name": "project-tracker", "url": "https://mcp.example.com/mcp"}],
    "defaultVaultIds": ["26d4b1a8-73c9-4f60-8a15-9e2c7b5d4f31"]
  }'

The response is the agent at its new version:

{
  "agentId": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
  "latestAgentVersionId": "7a4e1c95-6d2f-4380-b915-3e7a0c6f2d84",
  "mcpServers": [{ "name": "project-tracker", "url": "https://mcp.example.com/mcp" }],
  "defaultVaultIds": ["26d4b1a8-73c9-4f60-8a15-9e2c7b5d4f31"]
}

If the server project-tracker offers list_issues, the agent sees project-tracker__list_issues. The prefix keeps two servers from clashing. A new version replaces the whole definition, so send skills, tool settings, vault defaults, and every other field you want to keep. See Agents. Next, authenticate the server.

Server entry fields

Field	Description
`name`	The label the server’s tools are grouped under. Characters other than letters, digits, `_`, and `-` become `-` in tool names.
`url`	The server’s full Streamable HTTP endpoint, `http` or `https`, with no user name or password in it. Use `https` whenever a token is sent.
`headers`	Optional object of static header names to string values, sent during discovery and tool calls. Use it for nonsecret routing values, such as a service’s environment id.

Declared headers are part of agent and session configuration and can be read by users allowed to view that configuration. Keep secrets in a vault. Do not rely on a static header’s name or value to protect a secret.

Authenticate the server

Store the server’s token in a vault as a Token for an MCP server (bearer_token) whose server URL matches the agent’s url. Then grant the vault to the agent with defaultVaultIds, or to a session with vault_ids. If you narrow grants with credential refs, include this credential. Tokens that you paste are stored as-is and aren’t refreshed. If the server issues short-lived OAuth access tokens, rotate the credential before it expires.

A granted token also adds its server. A token for an MCP server in a granted vault adds its server’s tools to the session even if the agent doesn’t list that server. Those tools get a generated vault-... prefix. To keep a server out of a session, don’t grant the vault that holds its token, or leave the credential out of the credential refs.

How matching works

URLs match after lowercasing the scheme and host, dropping a default port (:443 or :80), and ignoring a trailing slash. A different path, subdomain, or port is a different server, so the token isn’t sent there.
The token is sent as Authorization: Bearer <token> by default. For a custom credential header such as X-Api-Key, set the vault bearer credential’s secret_name (API only) to the header name. The token is sent as-is under that name. Credential protection also applies to other permitted custom header names when they are bound this way through the vault.
If two granted vaults hold a token for the same server, the vault listed first in the session’s grants wins.
If no token matches, the session connects without one. That works for public servers and fails for servers that need authorization.

Test a server before you use it

probeMcpServer makes one live connection using the same URL matching and vault lookup as a session. It creates and changes nothing, but it needs the Developer or Admin role, like creating resources. See Organizations and roles. Omit vault_ids to test without a token.

Console
cURL

In the sidebar, click Credential vaults and open the vault.
Expand the server’s Token for an MCP server row. It shows whether the server is reachable and how many tools it offers.
Click Test again to run a new test.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/mcp/probe' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "server_url": "https://mcp.example.com/mcp",
    "vault_ids": ["26d4b1a8-73c9-4f60-8a15-9e2c7b5d4f31"]
  }'

{
  "ok": true,
  "reachable": true,
  "credential_matched": true,
  "deployment_authorized": false,
  "protocol_version": "2025-06-18",
  "server_name": "project-tracker",
  "tools": [
    { "name": "list_issues", "description": "List issues and their current status." }
  ]
}

A failed test still returns 200. Read the body:

Result	Meaning
`ok: true`	The server works with this token.
`ok: false`, `reachable: true`, no `protocol_version`	The server refused the token with `401` or `403`. It may be wrong or expired; check or rotate it.
`ok: false`, `reachable: true`, `protocol_version` set	The connection worked, but listing tools failed. Read `error`.
`ok: false`, `fault: egress_blocked`	The server URL points to a private, loopback, link-local, or metadata address, which Recursion refuses to connect to. Nothing was sent. Use a public server URL.
`ok: false`, `fault: token_invalid`	The stored token contains a line break, so it can’t be sent. Save it again without the line break.
`ok: false`, `reachable: false`, `credential_matched: true`	A token was sent, and the server couldn’t be reached or failed. Read `error`.
`ok: false`, `credential_matched: false`	No token was sent. Check the credential’s server URL and the vaults you named.

What success means: a passing test proves the server is reachable and that the token lets you list tools. It doesn’t prove that every tool call will succeed; permissions, arguments, and the server’s own state still matter.

Every test response field

Field	Meaning
`ok`	The server completed the handshake and returned its tool list.
`reachable`	The server answered. Either the handshake succeeded, even if listing tools then failed, or the server refused the token with `401` or `403`; in that case `protocol_version` is absent.
`credential_matched`	A token from the named vaults was attached. `false` means the test ran without a token.
`credential_unopenable`	A token matched the URL but couldn’t be used, so none was sent. `material_missing` means the credential has no stored value; re-enter it. `external_reference` means its value is held outside Recursion; re-enter it as a value.
`deployment_authorized`	Always `false` for servers you add in Recursion. You can ignore it.
`server_name`	What the server called itself. Use it to confirm you reached the right service.
`protocol_version`	The Model Context Protocol version the test used.
`tools`	The tools offered on this attempt, as the agent would see them before the name prefix.
`error`	Why the test failed. Never contains the token.
`fault`	Set when the test never reached the server for a reason other than the network. `egress_blocked` means the server URL points to a private or internal address; use a public URL. `token_invalid` means the stored token contains a line break; save it again without it. Absent otherwise, including real network failures.

A test gives up after 15 seconds. A server on a private, loopback, or link-local address is refused before anything is sent, so the test returns reachable: false and fault: egress_blocked with the reason in error.

How a session uses an MCP server

When a session starts, or moves to another agent version, it reads the MCP servers on that version.
For each server, it looks for a Token for an MCP server in the session’s granted vaults whose server URL matches.
It connects, lists the server’s tools, and fixes that list and the tool schemas until the session moves to another agent version.
The agent calls a tool as <server name>__<tool name>. The token is attached to every call outside the sandbox.

Tools, prompts, and resources: sessions use the server’s tools. Text and images that a tool returns are passed to the agent. Server prompts and standalone resources aren’t offered, and resource links in a result aren’t fetched.

Choose which tools an agent gets

A session receives every tool the server lists for its token. You can’t hide individual tools of a server. To limit what an agent can do, give it a token whose scopes allow only what it needs, or point it at a server that offers fewer tools.

Require approval before a tool runs

A server entry can name tools that run only after a person approves the exact call. Add an approval object with the API or an agent folder. The console keeps it when you save the agent, including on a server it generated from a vault credential, but doesn’t edit it yet. A gated server generated from a vault credential has no remove button, because removing the card alone would let the credential grant recreate it without its approval. It is reachable only while a granted credential claims its URL, so turning that credential off stops it; to remove the entry itself, delete it in Raw mode along with the credential. The console blocks a save that would keep such a server reachable without its approval. Exporting an agent from the console leaves a gated server out, along with any granted credential for its URL, and names both in the export’s notes, so you can add them again in the target organization with its approvers. Exporting to an agent folder keeps the approval object, including on a server generated from a vault credential, which the folder declares by its URL so the exported credential still reaches it gated. Neither export grants a credential for a gated server without its approval, because importing would regenerate the server from the credential ungated.

{
  "name": "github",
  "url": "https://api.githubcopilot.com/mcp/",
  "approval": {
    "tools": ["add_team_member"],
    "approvers": { "slack_user_ids": ["U0123ABCD", "W0456EFGH"] }
  }
}

tools names 1 to 64 tools, or is ["*"] to gate every tool the server offers, including tools it adds later. When the entry has allowed_tools, every gated tool must be in it.
approvers.slack_user_ids names 1 to 25 Slack users (IDs start with U or W). Only they can decide.
An empty approval, an empty list, or an unknown key is refused when you save the agent, so a typo can’t silently remove the gate.
Declare a gated endpoint once. A second entry with the same URL as a gated entry is refused, because only one of them would apply.
Give a gated server and its vault credential exactly the same URL. A session refuses to start its tools when a granted credential’s URL is a different spelling of a gated server’s URL (different case, extra slashes, or . and .. path segments), rather than send the credential without the approval.

When the agent calls a gated tool:

Recursion posts an approval card in the session’s Slack thread showing the tool, the server, and every argument, with Approve and Deny buttons. The arguments are shown as JSON. In the arguments and in the tool and server names, backticks and characters that can hide or reorder text (invisible, direction-changing and combining characters, and spaces other than a plain space) appear as \u escapes, so what you read is exactly what runs. Letters that only look like others, from a different alphabet, still appear as letters, so read names and values with care. The call doesn’t run, and the agent is told it is waiting.
An approver clicks. Anyone else who clicks sees a private note and nothing changes. The card updates to show who decided, and the session wakes with the decision.
After an approval, the agent calls the tool again with the same arguments, and the call runs once. A call with different arguments is a new request.

A request waits 24 hours for a decision, and an approval waits 24 hours to be used; after that it expires and the agent must ask again. A denial stands for that exact call in the session. Each session tree can make at most 50 requests. A call whose arguments would take more than 24 KiB to show is refused, because the card must show all of it. An approval belongs to the session that asked for it. A delegated agent in the same session tree can’t use it, even for the identical call. Approval needs a Slack-started session whose agent holds a Slack integration grant for that workspace, so the card can be posted. In any other session a gated tool is refused and doesn’t run. That includes sessions started from the console or a schedule, and delegated agents, which have no Slack thread of their own. A gated tool is also refused in a session whose Slack replies require review (slack_reply_review), because the card would post the arguments to Slack without that review. The approver list is fixed when a session starts; changing it affects new sessions only. The gate applies to tools reached through this server entry. A vault credential the agent can use for the same server under a different URL, or a native integration for the same vendor, is a separate tool surface and isn’t gated by this entry. A session refuses an entry that declares approval on an endpoint reached only through a native integration, rather than drop the gate and serve those tools ungated.

What happens when a server fails

At session start: an unreachable server, a rejected token, or a server that lists no tools doesn’t stop the session. Other servers still load, and the session’s events record a warning naming the servers: mcp_auth_rejected when a server refused the request, mcp_no_tools when a server answered but listed no tools, and mcp_discovery_failed for any other failure. Fix the token, or the URL or server, then start a new session. A running session lists a server’s tools again only when it moves to another agent version; moving it to the version it already runs changes nothing.
During a call: each request to the server has a 60-second timeout, and a response can be at most 8 MiB. A failed call returns an error to the agent as the tool result, and the agent can decide what to do next.

What can go wrong

The most common problems:

A session has an mcp_auth_rejected warning. The server refused the request with 401 or 403. If the warning says the session was granted no credential for the server, turn one on in the agent’s default credentials and save a new agent version, or grant the automation or session a vault that holds one. Otherwise check or rotate the token in the vault. Then start a new session.
A session has an mcp_no_tools warning. The server answered but listed no tools. Check that the server offers tools and that its credential grants access to them, then start a new session.
A session has an mcp_discovery_failed warning. The server was unreachable, failed the handshake, or is on a private address. Run a test with the same URL and vault, fix the cause, and start a new session.
Unexpected vault-... tools appear. A granted vault holds a token for an MCP server the agent doesn’t list. Remove the credential from the session’s grants, or add the server to the agent with a name you choose.

Every MCP server problem

Symptom or code	Cause	Fix
`400 invalid_request` on `server_url`	The URL is missing, isn’t `http` or `https`, has no host, or includes a user name or password.	Use the server’s full endpoint URL, and put the token in a vault.
`404 not_found` from a test	A vault in `vault_ids` doesn’t exist in your organization.	Check the vault id.
`403 forbidden` from a test	Your role doesn’t have the create permission, which a test needs.	See Organizations and roles. Use an account or key with the developer or admin role.
A session has an `mcp_auth_rejected` warning that says no credential was granted	The session sent no token: the agent version’s default credentials and the session’s vaults hold none for the server.	Turn one on in the agent’s default credentials and save a new agent version, or grant the automation or session a vault that holds one. Then start a new session.
A session has an `mcp_auth_rejected` warning	The server refused the token with `401` or `403`.	Check or rotate the token in the vault, then start a new session.
A session has an `mcp_no_tools` warning	The server answered but listed no tools: it offers none right now, or its credential grants access to none.	Check the server and its credential’s access, then start a new session.
A session has an `mcp_discovery_failed` warning	The server was unreachable, failed the handshake, or is on a private address.	Run a test with the same URL and vault, fix the cause, and start a new session.
The server’s tools are missing without a warning	The server isn’t on the agent version the session used, or the session started before you saved it.	Check the session’s agent version, then move the session to a version that has the server, or start a new session.
Unexpected `vault-...` tools appear	A granted vault holds a token for an MCP server the agent doesn’t list.	Remove the credential from the session’s grants, or add the server to the agent with a name you choose.
Tools worked yesterday and now fail with 401	A short-lived access token expired.	Rotate the credential.
A tool call times out	The server took longer than 60 seconds.	Make the tool faster, or have it return a job id the agent can check later.

For all error codes, see Errors. For limits, see Limits.

Next steps

Vaults and credentials

Store tokens for MCP servers and control which sessions receive them.

Agents

Publish a new agent version with its MCP servers attached.

Tools

See the built-in tools every session can use.

Events

Read discovery warnings and MCP tool calls in the session timeline.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Connect MCP servers

Add an MCP server to an agent

Authenticate the server

Test a server before you use it

How a session uses an MCP server

Choose which tools an agent gets

Require approval before a tool runs

What happens when a server fails

What can go wrong

Next steps

Vaults and credentials

Agents

Tools

Events