MCP Client

Overview

McpClient is the kernel's connection manager for external MCP (Model Context Protocol) servers. It handles the infrastructure side of MCP integration: establishing connections, tracking server status, and exposing available tools to the rest of the system.

This is distinct from the agent-facing side. The agent-facing interface for discovering and invoking MCP tools lives in MCP Servers. Think of McpClient as the device driver manager — it keeps connections alive so that agents can use them through higher-level APIs.

Provider examples: Claude Code MCP, Cursor MCP, VS Code Copilot MCP.

Connection Lifecycle

TypeScript API

import type {
  McpServerStatus,
  McpServerEntry,
  McpContext,
  McpActions,
  McpClient,
} from 'osprotocol/system/mcp-client'

McpServerStatus

type McpServerStatus = 'connected' | 'disconnected' | 'error'

Represents the current state of an MCP server connection.

McpServerEntry

interface McpServerEntry {
  name: string
  uri: string
  status: McpServerStatus
  tools?: string[]
  metadata?: Record<string, unknown>
}

A record describing a registered MCP server. tools lists the tool names exposed by the server. metadata holds any additional provider-specific information.

McpContext

interface McpContext {
  get(name: string): Promise<McpServerEntry | null>
  list(): Promise<McpServerEntry[]>
}

Read-only gather phase. Used to inspect the current state of registered servers without modifying connections.

McpActions

interface McpActions {
  connect(name: string, uri: string): Promise<McpServerEntry>
  disconnect(name: string): Promise<boolean>
}

Write/act phase. Used to establish or tear down server connections.

McpClient

interface McpClient {
  connect(name: string, uri: string): Promise<McpServerEntry>
  disconnect(name: string): Promise<boolean>
  get(name: string): Promise<McpServerEntry | null>
  list(): Promise<McpServerEntry[]>
}

The unified interface combining both context and actions. McpClient is the primary surface for code that needs both read and write access to MCP connections.

Usage Examples

Connect to an MCP server

const entry = await mcpClient.connect(
  'claude-code',
  'mcp://localhost:3100'
)

console.log(entry.status)  // 'connected'
console.log(entry.tools)   // ['read_file', 'write_file', ...]

List all connected servers and their tools

const servers = await mcpClient.list()

for (const server of servers) {
  if (server.status === 'connected') {
    console.log(`${server.name}: ${server.tools?.join(', ')}`)
  }
}

Disconnect a server

const ok = await mcpClient.disconnect('claude-code')
console.log(ok)  // true

System MCP Client vs Actions MCP Servers

The system client keeps connections alive. The actions interface exposes those connections as callable tools for agents.

Integration

• MCP Servers (actions) — agent-facing tool invocation over MCP connections managed here
• Registry — discover available MCP servers before connecting
• Installer — provision and install MCP server binaries or packages