Skip to content
Agent Squad

MCP Tool Provider

MCPToolProvider is a drop-in replacement for AgentTools that connects one or more MCP (Model Context Protocol) servers to any agent-squad agent. Tools are fetched from the servers at startup and exposed to the agent with no extra wiring — the existing tool_config / toolConfig mechanism handles everything.

How it works

Section titled “How it works”
  1. You call await MCPToolProvider.create(servers) which connects to each MCP server and fetches its tool list before returning.
  2. The tool schemas (already JSON Schema) are passed through directly to the agent’s provider format (Bedrock, Anthropic, OpenAI).
  3. When the agent calls a tool, MCPToolProvider routes the call to the correct server and returns the result.
  4. Errors reported by the server (isError: true) are surfaced back to the model as an error string rather than crashing.

The async factory pattern is required because the agent needs tool definitions synchronously when building each API request. Using create() ensures the connection and tool list are ready before the agent is used.

Installation

Section titled “Installation”
Terminal window
npm install agent-squad
npm install @modelcontextprotocol/sdk

@modelcontextprotocol/sdk is a peer dependency — it is never installed automatically, only when you explicitly add it.

Basic usage

Section titled “Basic usage”
import { AgentSquad, BedrockLLMAgent, MCPToolProvider } from "agent-squad";


const provider = await MCPToolProvider.create([
  { type: "stdio", command: "uvx", args: ["my-mcp-server"] },
]);


const agent = new BedrockLLMAgent({
  name: "mcp-agent",
  description: "An agent that uses tools from an MCP server",
  toolConfig: { tool: provider },
});


const orchestrator = new AgentSquad();
orchestrator.addAgent(agent);


// When done, clean up server connections:
await provider.disconnect();

Transports

Section titled “Transports”

MCPToolProvider supports two transports.

stdio — spawn a local process

Section titled “stdio — spawn a local process”

The most common transport. Agent Squad launches the MCP server as a subprocess and communicates over stdin/stdout.

import { MCPToolProvider } from "agent-squad";


const provider = await MCPToolProvider.create([
  {
    type: "stdio",
    command: "uvx",
    args: ["my-mcp-server", "--config", "config.json"],
    env: { API_KEY: process.env.MY_API_KEY! },
  },
]);

SSE — connect to a remote server

Section titled “SSE — connect to a remote server”

Connect to an MCP server running over HTTP Server-Sent Events (SSE).

import { MCPToolProvider } from "agent-squad";


const provider = await MCPToolProvider.create([
  {
    type: "sse",
    url: "http://localhost:3000/sse",
    headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
  },
]);

Multiple servers

Section titled “Multiple servers”

You can connect to multiple MCP servers at once. Tools from all servers are merged into a single flat list. If two servers expose a tool with the same name, the first server’s tool wins.

import { MCPToolProvider } from "agent-squad";


const provider = await MCPToolProvider.create([
  { type: "stdio", command: "uvx", args: ["filesystem-server"] },
  { type: "stdio", command: "uvx", args: ["database-server"] },
  { type: "sse",   url: "https://api.example.com/mcp" },
]);

Using with any agent

Section titled “Using with any agent”

MCPToolProvider works with every agent that accepts AgentTools — just drop it in as the tool value.

import { AnthropicAgent, OpenAIAgent, MCPToolProvider } from "agent-squad";


const mcpTools = await MCPToolProvider.create([
  { type: "stdio", command: "uvx", args: ["my-mcp-server"] },
]);


// Anthropic
const anthropicAgent = new AnthropicAgent({
  name: "anthropic-agent",
  description: "Agent with MCP tools",
  apiKey: process.env.ANTHROPIC_API_KEY!,
  toolConfig: { tool: mcpTools },
});


// OpenAI
const openaiAgent = new OpenAIAgent({
  name: "openai-agent",
  description: "Agent with MCP tools",
  apiKey: process.env.OPENAI_API_KEY!,
  toolConfig: { tool: mcpTools },
});

Configuration reference

Section titled “Configuration reference”

MCPServerConfig

Section titled “MCPServerConfig”

| Field | Type | Required | Description | |---|---|---|---| | type | "stdio" \| "sse" | Yes | Transport type | | command | string | stdio only | Executable to launch | | args | string[] | No | Arguments for the command | | env | Record<string, string> | No | Environment variables for the subprocess | | url | string | sse only | Full URL of the SSE endpoint | | headers | Record<string, string> | No | HTTP headers for the SSE connection |

MCPToolProvider

Section titled “MCPToolProvider”

| Parameter | Type | Required | Description | |---|---|---|---| | servers | MCPServerConfig[] | Yes | List of MCP servers to connect to | | callbacks | AgentToolCallbacks | No | Lifecycle hooks for tool start/end/error |