MCP Integration

How Orca uses the Model Context Protocol to give agents a unified interface for platform tools and external APIs.

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, the runner spins up a session-scoped MCP server at:

POST /runner/sessions/{sessionId}/mcp

This endpoint uses MCP’s streamable HTTP transport and serves:

1. Platform tools — the session’s scoped toolkit (tools allowed by the profile)
2. External MCP servers — inline servers defined in the profile’s mcpServers list
3. 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
general	Vercel AI SDK @ai-sdk/mcp — native MCP client
claude	Native SDK tool surface (MCP bridge in progress)
codex	Native SDK tool surface (MCP bridge in progress)

The general runtime has full MCP client support via @ai-sdk/mcp. Claude and Codex runtimes currently use native SDK tool surfaces; MCP bridging is tracked on the roadmap.

---

External MCP Servers in Profiles

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

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

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), the placeholder is passed through as-is. This will likely cause the external MCP server to reject the request. 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://db.internal/mcp",
  "headers": { "Authorization": "Bearer ${DB_API_KEY}" }
}

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

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

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:

1. Accept POST / requests with MCP protocol messages (JSON-RPC 2.0)
2. Return Server-Sent Events for streaming responses
3. 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