From 89675c2366458f87beb5611282014d7ea2eb6c16 Mon Sep 17 00:00:00 2001 From: Corneliu Croitoru Date: Mon, 6 Jul 2026 22:48:29 +0200 Subject: [PATCH] docs: add MCPToolProvider documentation and sidebar entry Adds a dedicated page for MCPToolProvider covering both Python and TypeScript, with sections for stdio/SSE transports, multiple servers, agent compatibility, and a full configuration reference. Updates the sidebar to expand 'Tools for Agents' into a section. Closes #299 Co-Authored-By: Claude Sonnet 4.6 --- docs/astro.config.mjs | 8 +- .../content/docs/agents/mcp-tool-provider.mdx | 282 ++++++++++++++++++ 2 files changed, 289 insertions(+), 1 deletion(-) create mode 100644 docs/src/content/docs/agents/mcp-tool-provider.mdx diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index c969d558..f69a5f02 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -82,7 +82,13 @@ export default defineConfig({ ] }, { label: 'Custom Agents', link: '/agents/custom-agents' }, - { label: 'Tools for Agents', link: '/agents/tools' }, + { + label: 'Tools for Agents', + items: [ + { label: 'Overview', link: '/agents/tools' }, + { label: 'MCP Tool Provider', link: '/agents/mcp-tool-provider' }, + ] + }, ] }, diff --git a/docs/src/content/docs/agents/mcp-tool-provider.mdx b/docs/src/content/docs/agents/mcp-tool-provider.mdx new file mode 100644 index 00000000..acc7a579 --- /dev/null +++ b/docs/src/content/docs/agents/mcp-tool-provider.mdx @@ -0,0 +1,282 @@ +--- +title: MCP Tool Provider +description: Connect MCP (Model Context Protocol) servers to any agent-squad agent as a drop-in tool source +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +`MCPToolProvider` is a drop-in replacement for `AgentTools` that connects one or more [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers to any agent-squad agent. Tools are fetched from the servers at runtime and exposed to the agent with no extra wiring — the existing `tool_config` / `toolConfig` mechanism handles everything. + +## How it works + +1. On the first tool use, `MCPToolProvider` connects to each configured MCP server and lists its tools. +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. + +Connections are lazy — nothing happens until the agent actually needs tools — and are reused for the lifetime of the provider instance. + +## Installation + + + +```bash +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. + + +```bash +pip install "agent-squad[mcp]" +``` +The `mcp` extra is optional — it is not pulled in when you install the base package. + + + +## Basic usage + + + +```typescript +import { AgentSquad, BedrockLLMAgent, MCPToolProvider } from "agent-squad"; + +const agent = new BedrockLLMAgent({ + name: "mcp-agent", + description: "An agent that uses tools from an MCP server", + toolConfig: { + tool: new MCPToolProvider([ + { type: "stdio", command: "uvx", args: ["my-mcp-server"] }, + ]), + }, +}); + +const orchestrator = new AgentSquad(); +orchestrator.addAgent(agent); +``` + + +```python +from agent_squad import AgentSquad +from agent_squad.agents import BedrockLLMAgent, BedrockLLMAgentOptions +from agent_squad.tools import MCPToolProvider, MCPServerConfig + +agent = BedrockLLMAgent(BedrockLLMAgentOptions( + name="mcp-agent", + description="An agent that uses tools from an MCP server", + tool_config={ + "tool": MCPToolProvider([ + MCPServerConfig(type="stdio", command="uvx", args=["my-mcp-server"]), + ]) + } +)) + +orchestrator = AgentSquad() +orchestrator.add_agent(agent) +``` + + + +## Transports + +`MCPToolProvider` supports two transports. + +### stdio — spawn a local process + +The most common transport. Agent Squad launches the MCP server as a subprocess and communicates over stdin/stdout. + + + +```typescript +import { MCPToolProvider } from "agent-squad"; + +const provider = new MCPToolProvider([ + { + type: "stdio", + command: "uvx", + args: ["my-mcp-server", "--config", "config.json"], + env: { API_KEY: process.env.MY_API_KEY! }, + }, +]); +``` + + +```python +from agent_squad.tools import MCPToolProvider, MCPServerConfig + +provider = MCPToolProvider([ + MCPServerConfig( + type="stdio", + command="uvx", + args=["my-mcp-server", "--config", "config.json"], + env={"API_KEY": os.environ["MY_API_KEY"]}, + ) +]) +``` + + + +### SSE — connect to a remote server + +Connect to an MCP server running over HTTP Server-Sent Events (SSE). + + + +```typescript +import { MCPToolProvider } from "agent-squad"; + +const provider = new MCPToolProvider([ + { + type: "sse", + url: "http://localhost:3000/sse", + headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` }, + }, +]); +``` + + +```python +from agent_squad.tools import MCPToolProvider, MCPServerConfig + +provider = MCPToolProvider([ + MCPServerConfig( + type="sse", + url="http://localhost:3000/sse", + headers={"Authorization": f"Bearer {os.environ['MCP_TOKEN']}"}, + ) +]) +``` + + + +## 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. + + + +```typescript +import { MCPToolProvider } from "agent-squad"; + +const provider = new MCPToolProvider([ + { type: "stdio", command: "uvx", args: ["filesystem-server"] }, + { type: "stdio", command: "uvx", args: ["database-server"] }, + { type: "sse", url: "https://api.example.com/mcp" }, +]); +``` + + +```python +from agent_squad.tools import MCPToolProvider, MCPServerConfig + +provider = MCPToolProvider([ + MCPServerConfig(type="stdio", command="uvx", args=["filesystem-server"]), + MCPServerConfig(type="stdio", command="uvx", args=["database-server"]), + MCPServerConfig(type="sse", url="https://api.example.com/mcp"), +]) +``` + + + +## Using with any agent + +`MCPToolProvider` works with every agent that accepts `AgentTools` — just drop it in as the `tool` value. + + + +```typescript +import { AnthropicAgent, OpenAIAgent, MCPToolProvider } from "agent-squad"; + +const mcpTools = new MCPToolProvider([ + { 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 }, +}); +``` + + +```python +from agent_squad.agents import AnthropicAgent, AnthropicAgentOptions +from agent_squad.agents import OpenAIAgent, OpenAIAgentOptions +from agent_squad.tools import MCPToolProvider, MCPServerConfig + +mcp_tools = MCPToolProvider([ + MCPServerConfig(type="stdio", command="uvx", args=["my-mcp-server"]), +]) + +# Anthropic +anthropic_agent = AnthropicAgent(AnthropicAgentOptions( + name="anthropic-agent", + description="Agent with MCP tools", + api_key=os.environ["ANTHROPIC_API_KEY"], + tool_config={"tool": mcp_tools}, +)) + +# OpenAI +openai_agent = OpenAIAgent(OpenAIAgentOptions( + name="openai-agent", + description="Agent with MCP tools", + api_key=os.environ["OPENAI_API_KEY"], + tool_config={"tool": mcp_tools}, +)) +``` + + + +## Configuration reference + +### 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` | No | Environment variables for the subprocess | +| `url` | `string` | sse only | Full URL of the SSE endpoint | +| `headers` | `Record` | No | HTTP headers for the SSE connection | + + +| Field | Type | Required | Description | +|---|---|---|---| +| `type` | `str` (`"stdio"` or `"sse"`) | Yes | Transport type | +| `command` | `str` | stdio only | Executable to launch | +| `args` | `list[str]` | No | Arguments for the command | +| `env` | `dict[str, str]` | No | Environment variables for the subprocess | +| `url` | `str` | sse only | Full URL of the SSE endpoint | +| `headers` | `dict[str, str]` | No | HTTP headers for the SSE connection | + + + +### 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 | + + +| Parameter | Type | Required | Description | +|---|---|---|---| +| `servers` | `list[MCPServerConfig]` | Yes | List of MCP servers to connect to | +| `callbacks` | `AgentToolCallbacks` | No | Lifecycle hooks for tool start/end/error | + +