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/client   # MCP SDK v2 — recommended

Or the v1 SDK, if you only talk to servers on protocol 2025-11-25 or older:

Terminal window
npm install @modelcontextprotocol/sdk

Both are optional peer dependencies — never installed automatically. When both are present, MCPToolProvider uses v2.

| Installed package | MCP protocol versions | Notes | |---|---|---| | @modelcontextprotocol/client >= 2.0.0 | 2026-07-28 and all legacy versions | auto-negotiated per server (server/discover probe with initialize fallback); Node >= 20 | | @modelcontextprotocol/sdk >= 1.0.0 | 2025-11-25 and older | the v1 package will never support 2026-07-28 |

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 three transports: stdio, streamable-http, and sse.

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! },
  },
]);

Streamable HTTP — connect to a remote server

Section titled “Streamable HTTP — connect to a remote server”

The current standard HTTP transport for remote MCP servers. Use this for any server you don’t spawn locally, unless it only speaks the older SSE protocol.

import { MCPToolProvider } from "agent-squad";


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

Requires @modelcontextprotocol/client (any version) or @modelcontextprotocol/sdk >= 1.10.

SSE — connect to a legacy remote server

Section titled “SSE — connect to a legacy remote server”

Connect to an MCP server running over HTTP Server-Sent Events (SSE). This is the older HTTP transport, deprecated by the MCP spec since 2025-03-26 — prefer streamable-http for servers that support it.

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: "streamable-http", 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 },
});

Tool UI (widgets)

Section titled “Tool UI (widgets)”

If an MCP server advertises a UI widget on a tool — via _meta.ui.resourceUri (or the OpenAI openai/outputTemplate alias), the same “MCP Apps” contract ChatGPT Apps use — MCPToolProvider surfaces it instead of flattening the result to text. On a call it reads the result’s structuredContent, fetches the advertised UI resource (resources/read, cached), and returns a ToolResult carrying a UIPayload (its resource URI, MIME type, template, render-only structured content, and meta). Tools whose _meta.ui.visibility excludes model stay callable but are never advertised to the LLM.

Pair the provider with a GroundedAgent and the widget is forwarded to the caller on the streaming response, exactly like a native tool that returns a UIPayload — so the same MCP server that backs a ChatGPT App renders its widgets here. For a server that advertises no _meta.ui, the model sees the same text as before.

Available in the Python and TypeScript MCPToolProvider. See the GroundedAgent tool-UI notes for how the widget is delivered on the stream in each language.

Configuration reference

Section titled “Configuration reference”

MCPServerConfig

Section titled “MCPServerConfig”

| Field | Type | Required | Description | |---|---|---|---| | type | "stdio" \| "streamable-http" \| "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 | streamable-http / sse | Full URL of the server endpoint | | headers | Record<string, string> | No | HTTP headers for the 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 |