MCP Bridge

Contents

Overview

flowchart LR
  subgraph External["External MCP Servers"]
    MCP1["MCP Server A"]
    MCP2["MCP Server B"]
  end
  subgraph Bridge["MCP Bridge"]
    Disc["Tool Discovery"]
    Schema["Schema Registration"]
    Filter["Allow/Deny Filter"]
  end
  subgraph Runtime["Agent Tool Runtime"]
    Builtin["Built-in Tools"]
    MCPTools["MCP Tools"]
    Skills["Skill Tools"]
    Dispatch["Tool Dispatcher"]
  end
  MCP1 --> Disc
  MCP2 --> Disc
  Disc --> Schema
  Schema --> Filter
  Filter --> MCPTools
  Builtin --> Dispatch
  MCPTools --> Dispatch
  Skills --> Dispatch

MCP tools are first-class citizens in the runtime. After discovery and schema registration, they are indistinguishable from built-in tools to the agent. The only difference is dispatch latency — MCP calls involve an IPC or network round-trip.

Decision Points

How It Works

Tool Runtime Initialization

The tool runtime (tool-runtime.helpers.ts) initializes three tool categories in a specific order: LSP tools (language server protocol), MCP tools (model context protocol), and codex tools (built-in). MCP initialization happens second because it may depend on LSP-provided workspace context:

// tool-runtime.helpers.ts — initialization sequence
export async function initializeToolRuntime(
  opts: AgentCommandOpts
): Promise<ToolRuntime> {
  const runtime: ToolRuntime = { tools: new Map(), cleanup: [] };

  // Phase 1: LSP tools (workspace-aware)
  await registerLspTools(runtime, opts.workspace);

  // Phase 2: MCP tools (external servers)
  const mcpConnections = await discoverAndConnectMcp(opts.mcpServers);
  for (const conn of mcpConnections) {
    const tools = await conn.listTools();
    for (const tool of tools) {
      if (passesFilter(tool.name, opts.toolFilter)) {
        runtime.tools.set(tool.name, wrapMcpTool(tool, conn));
      }
    }
    if (opts.cleanupBundleMcpOnRunEnd) {
      runtime.cleanup.push(() => conn.close());
    }
  }

  // Phase 3: Built-in codex tools
  registerBuiltinTools(runtime, opts);

  // Phase 4: Skill-based tools
  const snapshot = await buildSkillSnapshot(opts.skills);
  registerSkillTools(runtime, snapshot);

  return runtime;
}

Skill Snapshot System

Skills are packaged as SkillSnapshot objects that capture everything needed to invoke a skill at a point in time. The snapshot system (skills-runtime.ts) resolves skill definitions, matches them to the runtime environment, and builds immutable snapshots:

// skills-runtime.ts — SkillSnapshot type
interface SkillSnapshot {
  id: string;                          // Unique skill identifier
  version: string;                     // Snapshot version for cache invalidation
  prompt: string;                      // Resolved prompt text
  skills: ResolvedSkill[];             // List of resolved skill definitions
  agentFilter: NormalizedAgentFilter;  // Tool allow/deny list
  environment: SkillEnvironment;       // Detected runtime (brew/npm/go/uv)
}

interface ResolvedSkill {
  name: string;
  description: string;
  inputSchema: TSchema;                // TypeBox schema for skill parameters
  executor: SkillExecutor;             // Function that runs the skill
  tags: string[];                      // Environment tags for matching
}

interface NormalizedAgentFilter {
  allow?: string[];                    // Allowlist of tool names (glob patterns)
  deny?: string[];                     // Denylist of tool names (glob patterns)
}

// Environment detection
type SkillEnvironment = "brew" | "npm" | "go" | "uv" | "system";

function detectEnvironment(): SkillEnvironment {
  if (process.env.HOMEBREW_PREFIX) return "brew";
  if (existsSync("package.json")) return "npm";
  if (existsSync("go.mod")) return "go";
  if (existsSync("pyproject.toml")) return "uv";
  return "system";
}

Tool Allow/Deny Filtering

The agent-level filter restricts which tools can be invoked, regardless of whether they are built-in, MCP, or skill-based. Filters use glob patterns for flexible matching:

// Filter evaluation
function passesFilter(toolName: string, filter: NormalizedAgentFilter): boolean {
  // If allowlist exists, tool must match at least one pattern
  if (filter.allow && filter.allow.length > 0) {
    const allowed = filter.allow.some(pattern => minimatch(toolName, pattern));
    if (!allowed) return false;
  }
  // If denylist exists, tool must not match any pattern
  if (filter.deny && filter.deny.length > 0) {
    const denied = filter.deny.some(pattern => minimatch(toolName, pattern));
    if (denied) return false;
  }
  return true;
}

// Example filter configurations:
// Allow only read tools: { allow: ["read_*", "list_*"] }
// Block exec tools:      { deny: ["exec", "process_*"] }
// Allow everything:      {} (empty filter)

Runtime Extensions

The extension system (extensions.ts) manages the broader lifecycle of runtime extensions, of which MCP tool servers are one category. Extensions can also provide provider adapters, channel handlers, and lifecycle hooks:

Spawned Agent MCP Connections

When an agent spawns a child agent via sessions-spawn-tool.ts, the child can either inherit the parent’s MCP connections or establish its own. This is controlled by the spawn configuration:

// sessions-spawn-tool.ts — MCP inheritance
interface SpawnConfig {
  inheritMcp: boolean;         // true = share parent's MCP connections
  mcpServers?: McpServerDef[]; // Additional MCP servers for child only
  toolFilter?: NormalizedAgentFilter;  // Child-specific filter
}

async function spawnAgent(config: SpawnConfig, parentRuntime: ToolRuntime) {
  const childOpts: AgentCommandOpts = {
    mcpServers: config.inheritMcp
      ? [...parentRuntime.mcpConnections, ...(config.mcpServers ?? [])]
      : config.mcpServers ?? [],
    toolFilter: config.toolFilter ?? { allow: ["*"] },
    cleanupBundleMcpOnRunEnd: !config.inheritMcp,
  };
  return initializeToolRuntime(childOpts);
}

MCP Connection Lifecycle

sequenceDiagram
  participant Agent as Agent Runtime
  participant Helper as tool-runtime.helpers
  participant MCP as MCP Server
  participant Skills as skills-runtime
  participant Dispatch as Tool Dispatcher

  Agent->>Helper: initializeToolRuntime(opts)
  Helper->>MCP: connect(serverConfig)
  MCP-->>Helper: connection established
  Helper->>MCP: listTools()
  MCP-->>Helper: tool definitions + schemas
  Helper->>Helper: passesFilter(tool, opts.toolFilter)
  Helper->>Agent: wrapMcpTool(tool, conn)
  Agent->>Skills: buildSkillSnapshot(opts.skills)
  Skills-->>Agent: SkillSnapshot
  Agent->>Dispatch: register all tools

  Note over Agent,Dispatch: Runtime ready — tools invokable

  Agent->>Dispatch: tool call from LLM
  Dispatch->>MCP: execute(toolName, args)
  MCP-->>Dispatch: tool result
  Dispatch-->>Agent: tool_result message

  Note over Agent,MCP: On run end (if cleanupBundleMcpOnRunEnd)
  Agent->>MCP: close()

The connection lifecycle is deterministic: connect → discover → filter → register → use → cleanup. Cleanup only runs if cleanupBundleMcpOnRunEnd is set; otherwise connections persist for the session duration, enabling reuse across multiple agent runs.

Annotated Code Walkthrough

Walk through connecting an MCP server, discovering its tools, and making them available to the agent:

// MCP server configuration
interface McpServerDef {
  id: string;                         // Unique server identifier
  transport: "stdio" | "http";        // Connection transport
  command?: string;                   // For stdio: subprocess command
  args?: string[];                    // For stdio: command arguments
  url?: string;                       // For http: server URL
  headers?: Record<string, string>;   // For http: custom headers
  toolFilter?: NormalizedAgentFilter; // Server-specific tool filter
}

// Example configurations
const servers: McpServerDef[] = [
  {
    id: "db-tools",
    transport: "stdio",
    command: "npx",
    args: ["-y", "@company/db-mcp-server"],
    toolFilter: { deny: ["drop_*"] },    // Never allow DROP operations
  },
  {
    id: "deploy-tools",
    transport: "http",
    url: "https://internal.company.com/mcp",
    headers: { Authorization: "Bearer ${DEPLOY_TOKEN}" },
  },
];

// MCP discovery and connection
async function discoverAndConnectMcp(
  servers: McpServerDef[]
): Promise<McpConnection[]> {
  const connections: McpConnection[] = [];

  for (const server of servers) {
    try {
      const conn = server.transport === "stdio"
        ? await connectStdio(server.command!, server.args ?? [])
        : await connectHttp(server.url!, server.headers);

      // Protocol handshake — negotiate capabilities
      await conn.initialize({ clientInfo: { name: "openclaw", version: "1.0" } });

      connections.push(conn);
    } catch (err) {
      console.warn(`MCP server ${server.id} failed to connect:`, err);
      // Non-fatal: agent runs without this server's tools
    }
  }
  return connections;
}

// Wrapping MCP tools as AnyAgentTool
function wrapMcpTool(tool: McpToolDef, conn: McpConnection): AnyAgentTool {
  return {
    name: tool.name,
    description: tool.description,
    schema: convertJsonSchemaToTypebox(tool.inputSchema),
    metadata: {
      category: inferCategory(tool.name),
      ownerOnly: false,
      sandboxRequired: false,
    },
    async execute(args, ctx) {
      const result = await conn.callTool(tool.name, args);
      return {
        content: result.content,
        isError: result.isError ?? false,
      };
    },
  };
}

// skills-runtime.ts — building and registering skill tools
async function buildSkillSnapshot(
  skillDefs: SkillDefinition[]
): Promise<SkillSnapshot> {
  const env = detectEnvironment();
  const resolved = skillDefs
    .filter(s => s.tags.length === 0 || s.tags.includes(env))
    .map(s => resolveSkill(s, env));

  return {
    id: crypto.randomUUID(),
    version: computeHash(resolved),
    prompt: resolved.map(s => s.prompt).join("\n"),
    skills: resolved,
    agentFilter: { allow: ["*"] },
    environment: env,
  };
}

function registerSkillTools(runtime: ToolRuntime, snapshot: SkillSnapshot) {
  for (const skill of snapshot.skills) {
    runtime.tools.set(skill.name, {
      name: skill.name,
      description: skill.description,
      schema: skill.inputSchema,
      metadata: { category: "exec", ownerOnly: false, sandboxRequired: false },
      execute: (args, ctx) => skill.executor(args, ctx),
    });
  }
}

Edge Cases & Error Handling

Configuration

Related Topics

See also:

• Tool Use overview — parent module covering all tool-related subsystems
• Function Calling — how tool calls are validated, repaired, and dispatched
• Sandbox Execution — Docker/SSH backends for isolated tool execution

Directory Map

src/agents/tools/
├── tool-runtime.helpers.ts         ← Tool runtime initialization (LSP, MCP, codex)
├── skills-runtime.ts               ← Skill snapshot building and invocation
├── extensions.ts                   ← Runtime extension management
├── sessions-spawn-tool.ts          ← Agent spawning with MCP connection inheritance
├── mcp/
│   ├── connect-stdio.ts            ← Stdio transport connection
│   ├── connect-http.ts             ← HTTP transport connection
│   ├── protocol.ts                 ← MCP protocol handshake and message types
│   └── wrap-tool.ts                ← MCP tool → AnyAgentTool wrapper
└── filters/
    ├── agent-filter.ts             ← Allow/deny filter evaluation
    └── normalize-filter.ts         ← Filter pattern normalization