---
title: MCP Toolset
description: Connect a stdio MCP server to an SDK agent by projecting its tools into AI SDK tools.
---

`createMcpToolset` connects to a Model Context Protocol server over stdio, lists its tools once, and returns an AI SDK-compatible `tools` record for an SDK agent. This is the inbound MCP integration path: use any MCP server as an agent tool provider without writing one wrapper per external service.

For the opposite direction, where an MCP-aware client drives Smithers workflows, see [MCP Server](/integrations/mcp-server).

## Import

```ts
import { OpenAIAgent } from "smithers-orchestrator";
import {
  createMcpToolset,
  type McpServerConfig,
  type McpToolset,
  type McpToolsetOptions,
} from "@smithers-orchestrator/agents/mcp/createMcpToolset";
```

`createMcpToolset` is intentionally a deep import from `@smithers-orchestrator/agents/mcp/createMcpToolset`; it is not re-exported from the top-level `smithers-orchestrator` facade.

## Quick Start

```ts
const mcp = await createMcpToolset({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN ?? "" },
});

try {
  const agent = new OpenAIAgent({
    model: "gpt-5.6-terra",
    instructions: "Use the available tools when they are relevant.",
    tools: mcp.tools,
  });

  // Pass `agent` to a <Task>.
} finally {
  await mcp.close();
}
```

Call `close()` in a `finally` block when the workflow process owns the connection. The MCP client and spawned server process stay open until `close()` resolves.

## API

```ts
type McpServerConfig = {
  command: string;
  args?: string[];
  env?: Record<string, string>;
  cwd?: string;
};

type McpToolsetOptions = {
  include?: string[];
  exclude?: string[];
  namePrefix?: string;
  clientName?: string;
  clientVersion?: string;
};

type McpToolset = {
  tools: Record<string, import("ai").Tool>;
  toolNames: string[];
  close: () => Promise<void>;
};

declare function createMcpToolset(
  config: McpServerConfig,
  options?: McpToolsetOptions,
): Promise<McpToolset>;
```

`command`, `args`, `env`, and `cwd` are passed to the MCP SDK stdio transport. The Smithers client identity defaults to `clientName: "smithers-mcp-toolset"` and `clientVersion: "0.0.0"`.

## Tool Curation

```ts
const github = await createMcpToolset(
  {
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-github"],
    env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN ?? "" },
  },
  {
    include: ["get_issue", "create_pull_request"],
    exclude: ["create_pull_request"],
    namePrefix: "github_",
  },
);
```

`include` and `exclude` match the original MCP server tool names before `namePrefix` is applied. If both match a tool, `exclude` wins. `toolNames` contains the final names after filtering and prefixing.

## Runtime Behavior

On connect, Smithers calls `tools/list` once and wraps every selected MCP tool with AI SDK `dynamicTool`. When an agent invokes one of those tools, the wrapper calls MCP `tools/call` with the original server tool name and the model-provided arguments.

Response handling is intentionally simple:

- Successful calls return `structuredContent` when the server provides it.
- Otherwise successful calls return the joined text content blocks.
- MCP tool errors return `{ error: true, message, status: "failed" }` so the agent can inspect and recover inside its tool loop.

Schema handling follows the MCP server's advertised `inputSchema`. If a server omits it, Smithers uses an empty object JSON schema.

## CLI Agents

CLI agents consume MCP through their native configuration surfaces, not through `createMcpToolset`. Claude Code, Kimi, and Amp expose MCP config flags; Codex reads MCP servers from `~/.codex/config.toml` or `codex mcp add`.

Use `createMcpToolset` when you are building an SDK-agent workflow with `AnthropicAgent`, `OpenAIAgent`, `HermesAgent`, or a raw AI SDK tool-loop agent.

## See Also

- [SDK Agents](/integrations/sdk-agents)
- [OpenAPI Tools](/concepts/openapi-tools)
- [MCP Server](/integrations/mcp-server)
- [`examples/mcp-integration`](https://github.com/smithersai/smithers/tree/main/examples/mcp-integration)
