Connecting External MCP Servers to the Agent SDK

Why MCP servers beat custom tools for common integrations

Building a custom tool requires writing a handler function, defining a Zod schema, packaging it into an in-process server. That is the right approach for proprietary integrations — your internal CRM, your billing API, something specific to your stack.

For everything else, check the MCP server directory first. Notion, Linear, GitHub, Slack, Figma — most major tools have MCP servers already built and maintained. You get the full integration without writing a line of tool code.

The Agent SDK makes this easy. Connecting an external MCP server is a few lines of configuration.

Connecting an MCP server

This example uses the Playwright MCP server, which gives your agent a browser for web automation tasks.

Find the server's installation instructions on its GitHub or documentation page. Most MCP servers provide a command and args configuration block.

for await (const message of query(messages(), {
  model: "claude-sonnet-4-5",
  mcpServers: {
    playwright: {
      command: "npx",
      args: ["@playwright/mcp@latest"],
    },
  },
  permissionMode: "bypassPermissions",
  dangerouslyAllowBypassPermissions: true,
})) {
  // handle messages
}

That is the entire integration. The agent now has access to every tool the Playwright MCP server exposes — browser navigation, form filling, screenshot capture, network request monitoring.

Debugging: logging active MCP servers

When you first connect a server, verify it loaded correctly by logging the system initialization message:

for await (const message of query(messages(), options)) {
  if (message.type === "system" && message.subtype === "init") {
    console.log("Active MCP servers:", message.mcp_servers);
  }
}

If your MCP server appears in that list, it is active and the agent can use its tools. If it does not appear, check the command and args values against the server's documentation.

Adding multiple servers

You can connect as many MCP servers as your use case requires:

mcpServers: {
  playwright: {
    command: "npx",
    args: ["@playwright/mcp@latest"],
  },
  notion: {
    command: "npx",
    args: ["-y", "@notionhq/notion-mcp-server"],
    env: {
      NOTION_API_KEY: process.env.NOTION_API_KEY,
    },
  },
  filesystem: {
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
  },
}

Pass API keys and tokens through the env field. The values come from your .env file — never hardcode them in the source.

Operator use cases for MCP servers

For operators managing multiple client engagements, combining a few of these creates a genuinely powerful workflow automation layer. An agent that can read a Notion database, pull data from Linear, write a summary, and post it to a Slack channel is a meaningful productivity system — not a demo.

When to use MCP servers vs custom tools

Use MCP servers when:

• The service has a maintained public MCP server
• You want the full API surface, not just specific endpoints
• Setup speed matters

Build custom tools when:

• The service has no MCP server
• You need a specific endpoint not covered by an existing server
• You want to control exactly what the agent can do with the integration

> Finding MCP servers: The MCP server directory at mcp.so and the Anthropic documentation list maintained servers. Most major tools have them now. Before writing a custom tool for a new integration, spend two minutes checking if one already exists.

---

Author: FractionalSkill