Prime Agent MCP Integrations: Extending AI Capabilities with Model Context Protocol

MCP integrations in Prime Agent are Python-backed skills that connect the AI to external services like Linear or Notion through the Model Context Protocol, exposing server-defined tools as async methods inside the IPython kernel while maintaining a minimal tool surface for the model.

MCP integrations transform Prime Agent from a standalone coding assistant into a connected workflow engine. According to the PrimeIntellect-ai/prime-agent source code, these integrations leverage the Model Context Protocol to securely link external APIs without expanding the host's native tool set. By implementing external capabilities as importable Python modules running inside the IPython kernel, Prime Agent gains domain-specific superpowers while keeping its architecture clean and extensible.

What Are MCP Integrations?

MCP (Model Context Protocol) integrations are specialized connectors that allow Prime Agent to interact with external services through a standardized protocol. Unlike traditional approaches that expose each external capability as a separate model tool, MCP integrations follow a single-tool design philosophy.

Each integration is implemented as a Python-backed skill that executes inside the IPython kernel. When enabled, these skills dynamically bind server-defined tools as async methods on importable Python modules. This architecture keeps the host's exposed tool surface minimal—the only host-exposed tool remains ipython—while granting the model rich, domain-specific capabilities through Python code execution.

How MCP Integrations Extend Prime Agent's Capabilities

MCP integrations extend Prime Agent's capabilities in three critical ways:

External Service Connectivity – Connect to productivity tools like Linear and Notion, or any custom-hosted MCP server, directly from agent conversations.

Runtime Tool Discovery – The model can inspect available capabilities at runtime using await integration.list_tools() and examine argument schemas via Python's help() system before invocation.

Dynamic Capability Expansion – Because the tool set is defined by the external MCP server rather than the host, developers can add new services by declaring server configurations in settings.json without modifying Prime Agent's core code.

Configuring MCP Integrations

Setting up an MCP integration follows a five-step workflow that handles server declaration, authentication, and skill enablement.

Declaring the Server

Add an entry under mcpServers in your settings.json configuration file, or rely on built-in entries from the BUILTIN_MCP_CATALOG:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@linear/sdk-mcp"]
    }
  }
}

Authentication Flow

Run /mcp login in the chat interface and select MCP Connections to initiate OAuth, or configure a static bearer token using the bearerTokenEnvVar field in your server declaration. Upon successful authentication, the host stores credentials in ~/.prime/agent/auth.json under the key mcp:<server>.

Loading the Skill

After login, the kernel automatically discovers the server's tool definitions and imports the skill package. The tools become available as async methods on the module namespace.

Using the Tools

Call tools using standard Python await syntax, or use the call_tool method for non-identifier names:

import linear

# Standard method call

issues = await linear.list_issues(team="Engineering")

# Tool names with hyphens require call_tool

results = await linear.call_tool("bulk-update", {"ids": [1, 2, 3]})

Error Handling

The integration raises specific exceptions for failure modes:

• NotEnabled – Credentials are missing or the integration is not authenticated
• McpToolError – The remote MCP server returned an error

Practical Usage Examples

Discovering and Calling Tools

import linear

# Discover available tools dynamically

for tool in await linear.list_tools():
    print(f"{tool['name']}: {tool['description']}")

# Call a specific tool

issues = await linear.list_issues(team="Engineering", limit=10)
print(issues)

Handling Non-Identifier Tool Names

Some MCP servers expose tools with names that aren't valid Python identifiers. Use the call_tool method:

import notion

# 'notion-search' contains a hyphen

results = await notion.call_tool("notion-search", {
    "query": "project roadmap",
    "limit": 5
})
print(results)

Authentication and Error Handling

from rlm import NotEnabled, McpToolError

try:
    await linear.create_issue(title="Bug Fix", project="UX")
except NotEnabled:
    print("Please run `/mcp login linear` to connect.")
except McpToolError as e:
    print(f"Tool execution failed: {e}")

Architectural Components

Three core files implement the MCP integration architecture in Prime Agent:

Core Python Base Class

The McpIntegration base class in prime-agent-runtime/src/rlm/mcp_base.py handles session creation, OAuth token refresh, and dynamic method binding. It transforms MCP server capabilities into importable Python modules with async method signatures.

TypeScript Provider Registration

packages/ai/src/mcp.ts registers MCP providers with the host system, exposing them to the UI layer and slash-command interface. This file bridges the Python runtime capabilities with the TypeScript-based host application.

Host-Side Management

packages/coding-agent/src/core/mcp/mcp-manager.ts contains the host-side MCP manager that orchestrates login flows, loads built-in catalogs, and gates skill enablement based on authentication status. It also processes entries from BUILTIN_MCP_CATALOG during startup.

The /mcp slash command declared in packages/coding-agent/src/core/slash-commands.ts provides the user interface for managing these connections.

Summary

• MCP integrations are Python-backed skills that connect Prime Agent to external services via the Model Context Protocol.
• Credentials are stored in ~/.prime/agent/auth.json and managed through the /mcp login slash command.
• Tools are exposed as async methods on importable modules (e.g., await linear.list_issues()).
• The architecture uses McpIntegration in mcp_base.py for Python-side implementation and mcp-manager.ts for host-side orchestration.
• Error handling distinguishes between missing credentials (NotEnabled) and remote failures (McpToolError).

Frequently Asked Questions

What is the difference between MCP integrations and regular Prime Agent tools?

Regular Prime Agent tools are native host functions exposed directly to the model, while MCP integrations are external capabilities accessed through Python imports inside the IPython kernel. This design keeps the model's tool surface minimal—only the ipython tool is exposed—while allowing unlimited extensibility through server-defined MCP tools that are discovered at runtime.

How does authentication work for MCP integrations?

Authentication occurs via OAuth flows or static bearer tokens configured in settings.json. When you run /mcp login, the host stores tokens in ~/.prime/agent/auth.json under the mcp:<server> namespace. The McpIntegration base class handles automatic token refresh and session management, ensuring credentials remain valid for subsequent API calls.

Can I create custom MCP integrations for private services?

Yes. You can declare custom MCP servers in your settings.json under the mcpServers key using any MCP-compatible server implementation. The host in packages/coding-agent/src/core/mcp/mcp-manager.ts will register your custom server alongside built-in entries, and the Python runtime will bind its tools as a new importable module following the same patterns as Linear or Notion.

What happens if an MCP tool call fails?

Failed calls raise specific exceptions that you can catch in your Python code. NotEnabled indicates missing or invalid credentials, prompting you to re-authenticate via /mcp login. McpToolError signals that the remote MCP server returned an error status, allowing you to handle business logic failures separately from authentication issues.

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