Skip to content

[Feature] agents: MCP client — consume external MCP servers as tools (SDK-free) #427

Description

@pathosDev

Part of the agents epic #421.

Rationale

MCP is the emerging standard for tool interop. Consuming external MCP servers turns every existing MCP tool into an actor-supervised tool for our agents. Per the dependency policy, the MCP tools subset (JSON-RPC over stdio / streamable HTTP) is implemented in-house@modelcontextprotocol/sdk is at most an optional convenience peer, never a requirement.

Scope

  • McpClientActor extends BrokerActor — inherits reconnect/backoff/CircuitBreaker, outbound buffer, and the options resolution (McpClientOptions per the AGENTS.md options family, HOCON under actor-ts.agents.mcp.<name>).
  • Transports: stdio (child process; Node/Bun) and streamable HTTP (all runtimes, via HttpClient).
  • On connect: tools/list → register one McpToolProxy per tool into the ToolRegistry, namespaced "<serverName>.<tool>"; re-sync on list-changed notifications; configurable behavior on disconnect (keep-and-fail vs. remove).
agents.mcp.connect('github', { transport: 'stdio', command: 'github-mcp-server' });
// tools appear namespaced as "github.search_issues" in the ToolRegistry

Documentation

"MCP" docs page (client half, EN + DE); JSDoc; CHANGELOG.

Acceptance

  • Integration test against a scripted MCP server fixture (stdio + HTTP): list/call/list-changed/disconnect paths; reconnect with backoff verified under ManualScheduler.

Non-goals

MCP resources/prompts (tools-only subset first); the server side (separate issue).

Relates

Epic #421; depends on the ToolRegistry issue (#423). Dependency policy #419.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions