Why now

MCP is the standard interface for connecting LLMs to external tools. Wrapping each MCP server manually via defineTool() is unnecessary friction.

See updated DECISIONS.md for full rationale.

Design

Core idea

One function that connects to an MCP server, discovers its tools, and registers them as standard ToolDefinitions in the existing ToolRegistry. No changes to the agent loop or tool executor.

import { connectMCPTools } from 'open-multi-agent/mcp'

const tools = await connectMCPTools({
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-github'],
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
})

const agent = await oma.runAgent({
  name: 'github-agent',
  model: 'claude-sonnet-4-20250514',
  tools: tools.map(t => t.name),
}, prompt)

Integration surface

Transport

Support stdio (local processes) first. SSE/streamable HTTP can follow if there's demand.

Lifecycle

connectMCPTools() returns tools + a disconnect() handle. User is responsible for cleanup. No magic.

Open questions

1. Tool naming collisions -- if an MCP server exposes a tool named bash, it conflicts with built-in. Namespace prefix (e.g. mcp_github/bash) or let user handle it?
2. Reconnection -- should we auto-reconnect on stdio crash, or just surface the error?

Acceptance criteria

• connectMCPTools(config) function that returns ToolDefinition[] + disconnect()
• stdio transport working
• @modelcontextprotocol/sdk as optional peer dep (zero impact when unused)
• Example: agent using an MCP GitHub server
• Tests with mocked MCP server
• README section on MCP usage

Non-goals

• SSE transport (follow-up)
• MCP resources/prompts (tools only for now)
• Auto-discovery of MCP servers