MCP servers

Agents in Orca Agent Engine call external systems through the Model Context Protocol (MCP). You declare MCP servers inline on the agent record; the runtime connects to each server, discovers the tools it exposes, and makes them available to the agent during a session. This is the primary way an agent reaches data and actions that live outside Agent Engine.

Get your registry endpoint

MCP servers live on the agent

MCP servers are not a standalone registry resource. There is no endpoint that creates, lists, or deletes an MCP server on its own: each agent carries its own mcp_servers array, and that array is versioned with the agent like system or tools. To change which servers an agent reaches, update the agent and send the full replacement array.

Each entry declares a logical name and the endpoint to dial:

An agent holds at most 20 mcp_servers entries.

Expose a server's tools

For the default harness, declaring a server makes it reachable; a tools entry decides which tools the agent may call and under what permission policy. Set type to mcp_toolset and point mcp_server_name at the server you declared.

{
  "name": "support-triage",
  "model": "claude-sonnet-4-6",
  "system": "You triage support tickets.",
  "mcp_servers": [
    { "name": "tickets", "type": "url", "url": "https://mcp.example.com/tickets" }
  ],
  "tools": [
    { "type": "agent_toolset" },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "tickets",
      "default_config": { "permission_policy": { "type": "always_ask" } }
    }
  ]
}

Both toolset types accept the same default_config and configs shape. For mcp_toolset, set configs[].name to a tool name the MCP server advertises; see Tools for the permission_policy and enabled fields, which apply the same way here.

On the default harness, MCP toolsets default to always_ask, so an agent pauses for approval before its first call to a newly declared server. See Permission policies to change that.

Default responses return the built-in toolset as agent_toolset_20260401, the dated Anthropic wire literal. Clients that send the orca-beta header receive the canonical agent_toolset name instead. Both forms are accepted on write.

Override servers for one session

A session inherits the pinned agent version's mcp_servers and tools. On the default harness, point one session at a different server without publishing a new agent version by sending an agent block when you update the session. $SESSION_ID is the id of an existing session:

curl -fsS -X POST "$ORCA_REGISTRY_URL/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "mcp_servers": [
        { "name": "tickets", "type": "url", "url": "https://mcp.staging.example.com/tickets" }
      ]
    }
  }'

The override replaces the list in full and accepts the same limits as the agent record: at most 20 servers and 128 tools.

How a tool call reaches the server

On the default harness, the agent never dials the MCP server directly. At session start the runtime rewrites every mcp_servers entry to point at the Agent Engine gateway and hands the rewritten map to the agent SDK:

1. The rewritten entry keeps the logical name but swaps the URL for the gateway URL, and adds an X-Orca-Backend header carrying that logical name plus a short-lived session JWT.
2. The gateway validates the JWT, resolves the logical name back to the real destination URL through the registry, and looks up the credential bound to that server.
3. The gateway injects the credential as an Authorization header, forwards the JSON-RPC envelope to the upstream server, and writes an audit record.

Two consequences matter when you design an agent:

• The sandbox never learns the real server URL. Internal MCP endpoints stay invisible to agent code and to the model.
• Credentials never enter the sandbox or the agent process. They resolve at the gateway only.

Resolved destinations pass gateway SSRF admission: HTTPS is required by default, and loopback, link-local, cloud metadata, and private addresses are denied unless an operator allowlists the host explicitly.

Authenticate to a server

If a server needs credentials, store them in a vault and reference the vault through vault_ids when you create the session. Credentials bind to a server by mcp_server_url, so the URL on the credential must match the URL in mcp_servers. The gateway normalizes both sides before comparing - it lowercases the scheme and host and strips default ports and trailing slashes - but the host and path must otherwise be identical.

For servers behind OAuth, use an mcp_oauth credential and run credential validation to confirm the token and refresh configuration work before you start a session.

Discover tools at runtime

On the default harness, one mcp_servers entry produces one MCP client, and the harness namespaces every tool it exposes: a tool the server advertises as create_issue on a server named github reaches the agent, the event stream, and permission policies as mcp__github__create_issue. Match on that form when you compare against a tool_use.name, and use it - or the mcp__<server>__* wildcard - when you write a policy.

StreamNative Cloud MCP service

StreamNative Cloud provides a managed MCP service that exposes your Pulsar and Kafka resources - topics, schemas, and administrative operations - as MCP tools that Orca agents can call. The service is documented in the StreamNative Cloud documentation:

Permissions

MCP servers are part of the agent resource. Treat every Workspace API key as full access to its Workspace's resources, and separate access with Workspaces. See Control registry access.

What's next