MCP Integration

What is MCP?

The Model Context Protocol (MCP) is an open standard for exposing tools to LLM agents over HTTP. Orca uses MCP as the universal tool interface: every session gets its own MCP endpoint, and agents discover and invoke tools through it.

Session-Scoped MCP Endpoint

When a session is created, Orca provisions a session-scoped MCP server for the agent. This endpoint uses MCP’s streamable HTTP transport and serves:

Platform tools: the session’s scoped toolkit (tools allowed by the profile)
External MCP servers: inline servers defined in the profile’s mcpServers list
Connected apps: provider-managed grants invoked through platform facade tools and the tenant-isolated MCP bridge

The runner passes sessionMcpUrl in the run envelope to the sidecar, which uses it to connect its MCP client.

How Tools Flow

The LLM sees platform tools and inline external MCP tools through one tool interface. Connected-app catalogs stay deferred: the model sees the search_connected_app_tools and call_connected_app_tool facade tools, then loads only the provider tool schemas it needs.

Provider Support

Runtime	MCP via
`vercel`	Vercel AI SDK `@ai-sdk/mcp`, native MCP client
`pi`	Native MCP client via the same per-session bridge used by `vercel`
`claude`	Native SDK `mcp` option, with full header pass-through per server
`codex`	Native SDK `mcp_servers` config; custom headers are unsupported (use `bearer_token_env_var` instead)
`marlin`	Native streamable-HTTP MCP client, connecting to both the platform endpoint and external servers; requires `workerMode=sandbox`

All five runtimes have native MCP client support. Codex is the one exception on headers: it supports only a URL and bearer_token_env_var, so custom headers on a profile’s mcpServers entry are ignored (surfaced as a warning) rather than sent.

External MCP Servers in Profiles

Add external MCP servers to a profile’s mcpServers array:

{
  "name": "data-analyst",
  "runtime": "vercel",
  "model": "anthropic:claude-sonnet-4-6",
  "systemPrompt": "You are a data analyst.",
  "tools": ["@introspection"],
  "mcpServers": [
    {
      "name": "warehouse",
      "transport": "http",
      "url": "https://mcp.example.com/warehouse",
      "headers": {
        "Authorization": "Bearer ${WAREHOUSE_API_KEY}",
        "X-Tenant": "acme-corp"
      }
    },
    {
      "name": "metrics-api",
      "transport": "http",
      "url": "https://mcp.example.com/metrics",
      "headers": {
        "X-API-Key": "${METRICS_API_KEY}"
      },
      "optional": true
    }
  ]
}

transport may be http or sse. An entry can also set optional: true to mark a dependency the agent can work without: if that server’s headers cannot be resolved, the server is skipped and the run continues without it rather than failing outright (see Secret Resolution below).

Secret Resolution

Header values containing ${VAR} are resolved from the runner’s environment. See Secrets for how these are provisioned:

If ${VAR} cannot be resolved (the env var is not set), resolution fails with an error. For a required server, the run is rejected outright. If the server entry sets optional: true, that server is skipped instead and the run continues without it. Always verify that runner environment variables are set for every placeholder used in profiles.

MCP Catalog

The MCP Catalog is a conductor-local registry of reusable MCP server definitions. It lets you pre-configure servers once and reference them when building profiles in the dashboard.

User-authored catalog entries are a convenience layer copied into profiles. Provider-managed entries also authorize connected-app calls: profiles store them as credential-free catalog://<name> references, and the runtime resolves them through the bridge rather than as native sidecar MCP transports.

Dashboard MCP Page

The dashboard groups MCP management into three tabs:

Tab	Purpose
Servers	Manual catalog entries and managed app-backed MCP servers. The table shows the server host, with the full URL available in the row tooltip.
Connected Apps	OAuth app gallery. Apps can be searched and filtered by category; connecting an app registers its MCP server automatically.
Connections	Active and in-flight OAuth connections. Revoke access from this table when an app-backed server should be disconnected.

In v1, Connected Apps uses Composio as its provider. App category labels come from the provider payload when available, with dashboard fallbacks for common app slugs so the gallery remains filterable while provider metadata rolls out. When a managed app is attached to a profile, its mcpServers entry has only a name and matching reference, for example {"name":"composio-gmail","ref":"catalog://composio-gmail"}. The runtime does not send the managed URL or provider credentials to the worker. Agents discover matching tools on demand with search_connected_app_tools and execute an exact result with call_connected_app_tool; both are part of @introspection.

Managing the Catalog

# List catalog entries
GET  /api/mcp-servers

# Add a server
POST /api/mcp-servers
{
  "name": "my-db",
  "transport": "http",
  "url": "https://mcp.example.com/database",
  "headers": { "Authorization": "Bearer ${DB_API_KEY}" }
}

# Update
PUT /api/mcp-servers/{name}

# Delete
DELETE /api/mcp-servers/{name}

# Probe a server definition without persisting it (tool count, latency)
POST /api/mcp-servers/test

Reserved Names

The name runner is reserved and cannot be used in the MCP catalog. It refers to the session-scoped platform MCP endpoint.

Writing an MCP-Compatible Tool Server

Any HTTP server implementing the MCP streamable HTTP transport can be attached to Orca profiles. Minimal requirements:

Accept POST / requests with MCP protocol messages (JSON-RPC 2.0)
Return Server-Sent Events for streaming responses
Handle tools/list and tools/call method calls

# Test your MCP server with curl
curl -X POST https://my-mcp-server.example.com/ \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

See the MCP specification for the full protocol reference.

Platform MCP vs External MCP

Feature	Platform MCP (session-scoped)	External MCP
Hosted by	Runner	You
Configured in	Profile `tools` list	Profile `mcpServers` list
Secret resolution	N/A (built-in)	`${VAR}` from runner env
Tool scoping	Enforced (HTTP 403 if out of scope)	Not enforced by Orca
Examples	`web_search`, `delegate_run`, `time_now`	`warehouse`, `company-db`, `github-api`

Get Started

Core Concepts

Guides

Runbooks

MCP Integration

What is MCP?

Session-Scoped MCP Endpoint

How Tools Flow

Provider Support

External MCP Servers in Profiles

Secret Resolution

MCP Catalog

Dashboard MCP Page

Managing the Catalog

Reserved Names

Writing an MCP-Compatible Tool Server

Platform MCP vs External MCP

​What is MCP?

​Session-Scoped MCP Endpoint

​How Tools Flow

​Provider Support

​External MCP Servers in Profiles

​Secret Resolution

​MCP Catalog

​Dashboard MCP Page

​Managing the Catalog

​Reserved Names

​Writing an MCP-Compatible Tool Server

​Platform MCP vs External MCP

What is MCP?

Session-Scoped MCP Endpoint

How Tools Flow

Provider Support

External MCP Servers in Profiles

Secret Resolution

MCP Catalog

Dashboard MCP Page

Managing the Catalog

Reserved Names

Writing an MCP-Compatible Tool Server

Platform MCP vs External MCP