Prime Agent MCP Server Integration: A Complete Technical Guide

Prime Agent integrates with MCP servers through a built-in Python SDK that exposes async APIs like list_tools and call_tool, while managing connections via a catalog-based system with OAuth authentication.

Prime Agent implements MCP (Model Context Protocol) server integration through a hybrid architecture combining TypeScript-based catalog management with a Python runtime SDK. This design allows users to interact with external tools from the REPL while the system handles OAuth flows, connection caching, and credential storage automatically. The integration layer is managed through the @earendil-works/pi-ai/mcp package and exposed to users as the plain Python module mcp.

Built-in MCP Catalog and OAuth Registration

Prime Agent ships with a curated catalog of MCP integrations that are registered at daemon startup. The system uses a declarative approach to define server endpoints and authentication requirements.

Catalog Definition

The built-in integrations are defined in packages/ai/src/mcp/catalog.ts within the BUILTIN_MCP_CATALOG constant. This array maps server names to their URLs and OAuth configurations:

// packages/ai/src/mcp/catalog.ts
export const BUILTIN_MCP_CATALOG: readonly McpCatalogEntry[] = [
  {
    server: "linear",
    label: "Linear",
    url: "https://mcp.linear.app/mcp",
    oauth: { kind: "oauth", label: "Linear" },
  },
  {
    server: "notion",
    label: "Notion",
    url: "https://mcp.notion.com/mcp",
    oauth: { kind: "oauth", label: "Notion" },
  },
];

OAuth Provider Registration

When the daemon initializes, the registerBuiltinMcpOAuthProviders() function iterates through the catalog and creates OAuth providers for each entry. This enables the /login command to drive browser-based authentication flows:

// packages/ai/src/mcp/catalog.ts
export function registerBuiltinMcpOAuthProviders(): void {
  for (const entry of BUILTIN_MCP_CATALOG) {
    if (entry.oauth?.kind !== "oauth") continue;
    const id = `mcp:${entry.server}`;
    if (getOAuthProvider(id)) continue;
    registerOAuthProvider(
      createMcpOAuthProvider({
        server: entry.server,
        label: entry.label,
        url: entry.url,
        scopes: entry.oauth.scopes,
        clientId: entry.oauth.clientId,
      })
    );
  }
}

The OAuth implementation resides in packages/ai/src/mcp/oauth.ts, which handles token exchange and storage without exposing secrets to the REPL environment.

Runtime Python SDK for MCP Operations

Inside every REPL kernel, the mcp module provides three primary async APIs for interacting with MCP servers:

• await mcp.list_tools(server) – Retrieves the JSON-described tool set for the specified server
• await mcp.call_tool(server, name, args) – Invokes a tool on the remote MCP server with arguments matching the tool's JSON schema
• await mcp.reload() – Forces the kernel to drop all cached connections and rediscover tools

These functions are thin wrappers around an underlying MCP client that communicates over HTTP or stdio child processes. The client instantiates lazily upon first reference to a server name, discovers available tools, and caches the connection for the kernel's lifetime.

Configuration changes in ~/.prime/agent/settings.json (such as adding new servers) automatically trigger connection replacement on the next call.

Adding Custom MCP Servers via CLI

Custom servers are not hard-coded; they are stored in the user settings file under the mcpServers key. Prime Agent provides CLI commands to register both HTTP-based and stdio-based servers:

# Add a remote HTTP-based server

prime-agent mcp add remote \
  --url https://mcp.example.com/mcp \
  --bearer-token-env-var EXAMPLE_TOKEN

# Add a stdio-based server (runs a local process)

prime-agent mcp add local \
  --cwd /abs/path \
  --env TOKEN=EXAMPLE_TOKEN \
  -- node server.js --stdio

These same commands work within the TUI via the /mcp command interface. All credentials are stored separately in ~/.prime/agent/auth.json under keys formatted as mcp:<server>, ensuring that secret values never appear in the settings file.

Authentication Lifecycle and Enable-by-Login

Built-in integrations ship in a disabled state, meaning they are omitted from the system prompt and not imported into the kernel. The enablement follows a specific lifecycle managed by packages/coding-agent/src/modes/interactive/interactive-mode.ts:

1. Skill package present but disabled – The integration code exists but remains dormant
2. Credential acquisition – User runs /mcp login <name> or uses the TUI flow to authenticate
3. Automatic reload – The system detects valid credentials, enables the skill, and imports it into the kernel
4. Logout disablement – Running /mcp logout <name> removes the credential and disables the skill

This design ensures that only authenticated, active integrations consume context window space and compute resources.

Error Handling

The MCP SDK defines specific exception types that surface as ordinary Python exceptions:

• NotEnabled – Raised when a built-in integration lacks valid credentials; prompts the user to run /mcp login
• McpToolError – Propagates errors returned by the remote MCP service

These exceptions can be caught using standard Python try/except blocks, allowing users to handle authentication failures or remote service errors gracefully within their REPL workflows.

Summary

Prime Agent's MCP server integration combines declarative catalog management with a dynamic Python SDK:

• Catalog layer (packages/ai/src/mcp/catalog.ts) defines built-in servers and registers OAuth providers at startup
• Runtime layer exposes mcp.list_tools(), mcp.call_tool(), and mcp.reload() to Python code with automatic connection caching
• Configuration layer stores custom servers in ~/.prime/agent/settings.json and secrets in ~/.prime/agent/auth.json
• Lifecycle management enables servers only after successful authentication through the /mcp login flow

Frequently Asked Questions

How does Prime Agent cache MCP server connections?

The MCP client instantiates lazily the first time a server name is referenced and maintains the connection for the kernel's lifetime. Calling await mcp.reload() forces the kernel to drop all cached connections and rediscover tools, which is useful after updating server configurations.

Where does Prime Agent store MCP server credentials?

Credentials are stored in ~/.prime/agent/auth.json under keys formatted as mcp:<server>. The runtime never writes secret values directly into ~/.prime/agent/settings.json, keeping sensitive data isolated from configuration files.

What happens when I try to use a built-in MCP server without logging in?

The system raises a NotEnabled exception and prompts you to run /mcp login <server_name>. Built-in integrations remain disabled and excluded from the system prompt until valid credentials are provided through the OAuth flow.

Can I use both HTTP and stdio-based MCP servers with Prime Agent?

Yes. Use prime-agent mcp add remote for HTTP-based servers or prime-agent mcp add local for stdio-based processes. Both types are managed through the same Python SDK interface (mcp.list_tools() and mcp.call_tool()) regardless of their underlying transport mechanism.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}