features mcp

MCP

Active contributors: Mario Zechner, kt, Armin Ronacher

Purpose

Prime Agent connects external services over the Model Context Protocol (MCP). Consistent with its single-tool design, MCP integrations are not exposed as new agent tools: each integration is a Python-backed skill the model imports and calls from the IPython kernel, and the host's only jobs are interactive login (browser OAuth) and credential storage/refresh in auth.json. The ai package provides the client catalog and the generic OAuth flow for MCP servers; the coding-agent package registers providers and gates integration skills by auth; the kernel runs the actual MCP client; and the web UI renders MCP tool calls as cards.

Built-in integrations ship disabled and are enabled by logging in. Currently supported built-ins are Linear and Notion, both remote HTTP servers. User-declared servers go under mcpServers in settings.

How it works

graph TD
    KERNEL["IPython kernel"]
    SKILL["Python skill (subclasses McpIntegration)"]
    MCP["mcp Python SDK (streamable HTTP)"]
    SRV["remote MCP server"]
    MANAGER["McpManager (coding-agent)"]
    OAUTH["mcp/oauth.ts createMcpOAuthProvider"]
    AUTH["auth.json (mcp:<server>)"]
    WEB["web MCP tool card"]

    SKILL --> KERNEL
    KERNEL --> MCP
    MCP --> SRV
    MANAGER --> OAUTH
    OAUTH --> AUTH
    MANAGER -. mcp.refresh / mcp.config .-> KERNEL
    SRV --> WEB

Loading

The ai client

packages/ai/src/mcp.ts re-exports ./mcp/index.js. packages/ai/src/mcp/index.ts exposes the catalog (McpCatalogEntry, BUILTIN_MCP_CATALOG, getCatalogEntry, registerBuiltinMcpOAuthProviders) and the OAuth provider factory (McpOAuthConfig, createMcpOAuthProvider).

packages/ai/src/mcp/catalog.ts defines the two built-in entries (Linear, https://mcp.linear.app/mcp; Notion, https://mcp.notion.com/mcp) and registerBuiltinMcpOAuthProviders, which registers each entry's OAuth provider under the id mcp:<server> so it reuses auth.json.

packages/ai/src/mcp/oauth.ts implements generic OAuth 2.1 for remote MCP servers: it discovers the authorization-server metadata at the URL's origin, performs dynamic client registration (RFC 7591) when the server supports it, starts a local callback server (ports 53700-53709), runs PKCE, exchanges the code for tokens, and refreshes expired tokens. The provider id is mcp:<server>.

The coding-agent integration

packages/coding-agent/src/core/mcp/mcp-manager.ts is the host side. McpManager resolves integrations from the built-in catalog plus Settings.mcpServers (HTTP entries only), registers OAuth providers for user servers, and gates each integration's skill by whether valid credentials exist (isAuthed). It also exposes host-request handlers to the kernel: mcp.refresh (refresh credentials under lock), mcp.config (resolve the server URL and extra headers, honoring a user url override), and mcp.begin_login (start interactive login). listStatus drives /mcp. Enablement is derived purely from credentials: /mcp login <name> or /login stores an OAuth credential, and a resource reload (or /reload) enables the corresponding skill.

The kernel side

prime-agent-runtime/src/rlm/mcp_base.py is the Python base class. McpIntegration connects with the mcp SDK over streamable HTTP, reads credentials from the host's auth.json (mcp:<server>), refreshes expired tokens by calling rlm.host_request("mcp.refresh", ...), auto-discovers the server's tools, and binds each as an async method. NotEnabled is raised when no credentials exist, McpToolError when a tool result is flagged as an error. A skill package subclasses McpIntegration, sets server (and url for remote servers), and is imported in the kernel like any other skill. Full authoring guidance is in packages/coding-agent/docs/mcp-integrations.md.

Web tool cards

MCP tool calls surface in the web chat through the MCP tool card. web/design/src/components/agent-elements/tools/mcp-tool.tsx renders McpTool: it derives an active/completed verb title from the tool's display name, shows the priority arguments as a subtitle, and renders the parsed JSON/text output in a collapsible code block. Output is normalized by unwrapMcpOutput before display.

Integration points

• The web card lifecycle is shared with other tool kinds; see Tool cards.
• The OAuth flow reuses the provider registry and callback-server pattern from the OAuth feature; see OAuth.
• Skills are described in Skills and the runtime in RLM runtime.

Entry points for modification

• Add a built-in integration: extend BUILTIN_MCP_CATALOG in packages/ai/src/mcp/catalog.ts and ship a skill package; document it in packages/coding-agent/docs/mcp-integrations.md.
• Extend the generic OAuth flow: packages/ai/src/mcp/oauth.ts.
• Change enablement or host-request handling: packages/coding-agent/src/core/mcp/mcp-manager.ts.
• Extend the kernel client: prime-agent-runtime/src/rlm/mcp_base.py.
• Adjust the web rendering: web/design/src/components/agent-elements/tools/mcp-tool.tsx.

Key source files

File	Purpose
packages/ai/src/mcp.ts	Root entry, re-exports ./mcp/index.js
packages/ai/src/mcp/index.ts	Public exports of catalog and OAuth factory
packages/ai/src/mcp/catalog.ts	BUILTIN_MCP_CATALOG, getCatalogEntry, provider registration
packages/ai/src/mcp/oauth.ts	createMcpOAuthProvider, OAuth 2.1 + PKCE + dynamic client registration
packages/coding-agent/src/core/mcp/mcp-manager.ts	McpManager: integration resolution, auth gating, host-request handlers
prime-agent-runtime/src/rlm/mcp_base.py	McpIntegration, NotEnabled, McpToolError, kernel MCP client
web/design/src/components/agent-elements/tools/mcp-tool.tsx	McpTool web tool card
packages/coding-agent/docs/mcp-integrations.md	User and authoring documentation

Related pages

• The packages behind these features, LLM provider abstraction and streaming, Web design
• OAuth - the provider registry and callback flow MCP reuses
• Tool cards - the tool-card lifecycle MCP cards participate in
• Features lens index, Glossary