Imported from elizaOS/eliza (plugins/plugin-mcp/AGENTS.md). Install upstream with npx skills add elizaOS/eliza --skill plugin-mcp. Copyright stays with the author.

@elizaos/plugin-mcp

elizaOS plugin that connects Eliza agents to external MCP (Model Context Protocol) servers, exposing their tools and resources as agent capabilities.

Purpose / role

Adds MCP client support to any Eliza agent. At runtime the plugin starts McpService, which connects to one or more MCP servers (stdio, SSE, or streamable-HTTP), discovers their tools and resources, and makes them available via a unified MCP action and MCP provider. The plugin is opt-in — add it to the plugins array in the character file and configure servers under settings.mcp.servers.

Plugin surface

The plugin also exports McpRouteContext (type) for host servers wiring up handleMcpRoutes.

Layout

plugins/plugin-mcp/
  src/
    index.ts                  Plugin object — registers McpService, MCP action, MCP provider
    types.ts                  All shared types + config guards (McpSettings, McpServerConfig,
                                McpServer, McpConnection, PingConfig, ToolSelectionSchema, …)
    service.ts                McpService — connection lifecycle, tool calls, resource reads,
                                ping monitoring, reconnect backoff
    provider.ts               MCP provider — formats connected-server summary for agent state
    routes-mcp.ts             handleMcpRoutes — /api/mcp/config, /api/mcp/status, marketplace
    mcp-marketplace.ts        Client for registry.modelcontextprotocol.io (search + details)
    prompts.ts                All Handlebars-style prompt templates (tool/resource
                                selection, reasoning, feedback, errorAnalysis)
    actions/
      mcp.ts                  mcpAction handler — op routing (call_tool / read_resource)
    templates/                Thin re-export shims over prompts.ts
      toolSelectionTemplate.ts
      toolReasoningTemplate.ts
      resourceSelectionTemplate.ts
      resourceAnalysisTemplate.ts
      feedbackTemplate.ts
      errorAnalysisPrompt.ts
    utils/
      error.ts                handleMcpError — error-to-response helper
      handler.ts              handleNoToolAvailable
      json.ts                 JSON parse helpers
      mcp.ts                  buildMcpProviderData
      processing.ts           processToolResult, processResourceResult, handleToolResponse,
                                handleResourceAnalysis, sendInitialResponse
      schemas.ts              ToolSelectionName, ToolSelectionArgument, ResourceSelection
                                types + JSON Schema objects + type guards
      selection.ts            createToolSelectionName, createToolSelectionArgument
      validation.ts           validateResourceSelection, feedback prompt builders
      wrapper.ts              withModelRetry — retry loop for model-parsed selections
    tool-compatibility/
      base.ts                 McpToolCompatibility base class + detectModelProvider
      index.ts                Factory: createMcpToolCompatibilitySync (Anthropic/OpenAI/Google)
      providers/              Per-provider schema fixup implementations
  __tests__/
    mcp-config-security.test.ts   Config validation / security tests
    integration/                  Integration test suite
  index.browser.ts          Browser-unavailable entry (MCP client is node-only)

Commands

All scripts in plugins/plugin-mcp/package.json:

bun run --cwd plugins/plugin-mcp build        # bun build.ts → dist/ (ESM + CJS + .d.ts)
bun run --cwd plugins/plugin-mcp dev          # hot-rebuild with bun --hot
bun run --cwd plugins/plugin-mcp test         # vitest run
bun run --cwd plugins/plugin-mcp typecheck    # tsc --noEmit
bun run --cwd plugins/plugin-mcp lint         # biome check --write --unsafe
bun run --cwd plugins/plugin-mcp lint:check   # biome check (read-only)
bun run --cwd plugins/plugin-mcp format       # biome format --write
bun run --cwd plugins/plugin-mcp format:check # biome format (read-only)
bun run --cwd plugins/plugin-mcp clean        # rm -rf dist .turbo

Config / env vars

Config is read from the character settings object (or runtime settings), plus optional per-server environment variables. The PATH env var is forwarded to stdio child processes automatically.

Transport config shapes (see src/types.ts):

• stdio: { type: "stdio", command: string, args?, env?, cwd?, timeoutInMillis? }
• HTTP/SSE: { type: "streamable-http"|"http"|"sse", url: string, timeout? }

The agentConfig.pluginParameters in package.json declares PATH and mcp for auto-config tooling.

Security: malformed settings and every unsafe server config fail service initialization. Each server is validated by @elizaos/core/security/mcp-server-config before connection is attempted, and every HTTP/SSE request uses core's DNS-pinned SSRF transport.

How to extend

Add a new transport type:

1. Extend McpServerConfig union in src/types.ts and add an is*Config guard.
2. Add a transport builder in src/service.ts mirroring buildStdioClientTransport / buildHttpClientTransport.
3. Branch in initializeConnection.

Add a new MCP op (e.g., list_prompts):

1. Add the op name to the McpOp union in src/actions/mcp.ts.
2. Add normalization in normalizeOp and text inference in inferOpFromText.
3. Implement a handleListPrompts function following the pattern of handleCallTool.
4. Branch in the handler function.
5. Add the op to McpService if it requires a new SDK call.

Add a new provider-specific tool compatibility rule:

1. Create a class in src/tool-compatibility/providers/ extending McpToolCompatibility.
2. Register it in src/tool-compatibility/index.ts under createMcpToolCompatibilitySync.

Add a new API route: Add a branch in src/routes-mcp.ts handleMcpRoutes. The host server passes a McpRouteContext; follow the existing GET /api/mcp/config pattern.

Conventions / gotchas

• Node-only. index.browser.ts is a browser-unavailable entry. The MCP SDK's stdio and SSE transports require Node.js APIs. The eliza.platforms field in package.json is ["node"].
• Service type key is lowercase "mcp". McpService.serviceType = "mcp", and core's service lookup is case-sensitive — always resolve via the MCP_SERVICE_NAME constant, never a hand-written string.
• Tool schema fixup runs synchronously. createMcpToolCompatibilitySync uses require() internally; this is intentional (called lazily during tool listing in fetchToolsList, not at import time).
• Ping monitoring is stdio-only. HTTP/SSE transports do not use the ping interval; reconnect is handled by transport error/close events.
• Config changes require a restart. The service reads settings.mcp once at init. restartConnection(name) re-initializes a single server without full restart; adding/removing servers requires plugin reinit.
• Security validation is blocking. validateMcpServerConfig from @elizaos/agent runs before every connection and spawn. Servers that fail validation are silently skipped (logged at error level).
• Marketplace is read-only. mcp-marketplace.ts queries https://registry.modelcontextprotocol.io to browse and discover MCP servers; it does not install them.
• promoteSubactionsToActions is applied to mcpAction in index.ts, so any sub-action expansion follows the elizaOS core convention.
• For architecture rules, logger conventions, ESM requirements, and naming standards, see the root CLAUDE.md.

Verification

Follow the repository-wide verification and evidence standard in the root CLAUDE.md. Run the package's relevant build, typecheck, lint, and test commands, then exercise the real integration boundary changed by the work. Inspect the produced domain artifacts and failure behavior; do not substitute mocked success for the system under test.