Connecting MCP Servers to Individual Agents

The Problem with Global MCP Configuration

When you configure an MCP server globally — in your project's .mcp.json or in settings — every session and every subagent can access it. For simple workflows, this is convenient. For complex multi-agent pipelines, it creates problems.

Imagine a pipeline with five agents: a researcher, a writer, a fact-checker, a formatter, and a publisher. The publisher agent needs a GitHub MCP server to create PRs. The researcher needs a web-search MCP server. If both are configured globally, every agent in the pipeline can access both servers — including agents that have no reason to touch GitHub or search the web.

Giving every agent every tool is the same mistake as not using tool allowlists. It increases the surface area for mistakes, slows agents down with unnecessary tool choices, and makes the pipeline harder to reason about.

The mcpServers Frontmatter Field

The mcpServers field in a subagent definition scopes MCP servers to that agent only. When the agent starts, it has access to the listed servers. Other agents in the same session do not.

Two ways to specify MCP servers: inline definitions and references.

Inline definition — specify the server directly in the agent file:

---
name: browser-tester
description: Tests web pages using browser automation. Use for any UI testing tasks.
tools: Read
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

You are a browser test agent. Use the playwright MCP server to interact with web pages...

Reference — point to a server already configured elsewhere:

---
name: github-publisher
description: Creates pull requests and manages GitHub operations.
mcpServers:
  - github
---

The reference form uses the server name from your existing MCP configuration. The agent gets access to that server; the inline definition does not need to repeat the connection details.

Transport Types

MCP servers communicate over one of four transport types. Choose based on where the server runs:

• stdio: The server runs as a local process, communicating over standard input/output. Most common for development and local tools.
• http: The server is a remote HTTP endpoint. Stateless — each request is independent.
• sse: Server-Sent Events — a remote server that streams events to the client. Good for servers that push notifications.
• ws: WebSocket — a persistent bidirectional connection to a remote server.

For most custom MCP servers you build yourself (following Track 11: Build MCP Servers), you will use stdio transport locally or http transport when deploying remotely.

Designing Agent-MCP Pairings

The principle is: match each MCP server to exactly the agent(s) that need it. Avoid giving MCP server access to agents that have no reason to use it.

A well-structured content pipeline might look like this:

• researcher-agent: mcpServers: [web-search, knowledge-base]
• writer-agent: no MCP servers (writes from researcher's summary)
• fact-checker-agent: mcpServers: [web-search]
• publisher-agent: mcpServers: [github, cms-api]

Each agent has exactly what it needs. The writer cannot accidentally search the web or publish to GitHub. The fact-checker cannot modify the CMS. The boundaries are enforced at the definition level.

MCP Servers and Skills in Subagents

If you have built custom MCP servers following Track 11, those servers can be paired with specialized subagents to create highly capable, narrowly scoped workers. A database-query agent with your internal analytics MCP server, a deployment agent with your infrastructure MCP server, a customer-data agent with your CRM MCP server.

Note one important limitation from the agent teams documentation: when a subagent definition is used as an agent team teammate rather than a regular subagent, the skills and mcpServers frontmatter fields are not applied. Teammates load skills and MCP servers from project and user settings instead. Per-agent MCP scoping applies to subagents, not to agent team teammates.