Claude Code Subagents: When They Help (and When They Hurt)
Claude Code subagents are best used as narrowly scoped workers with only the MCP access their task requires, not as a default layer for every coding job.
Claude Code subagents help when a self-contained task would pollute the main context or needs tightly scoped MCP access; they hurt when work depends on shared history, rapid feedback, or coordinated edits. Today, a custom subagent can inherit session MCP tools, reference a configured server, or start an inline server that only it can see.
Table of contents
- The short answer
- How it works today
- Step-by-step setup
- Claude Code vs other MCP clients
- The catch most guides skip
- What to connect first
The short answer
Use Claude Code subagents for bounded research, review, testing, or log-heavy work, especially when one worker needs an MCP server the parent should not load. Keep quick edits and context-dependent implementation in the main conversation, because delegation adds a new context, another model run, startup delay, and a summary boundary.
That distinction matters more than the number of agents. Anthropic describes subagents as separate workers with their own context window, system prompt, tool access, and permissions; only their result returns to the parent. The official Claude Code subagent documentation specifically recommends them for work that would otherwise fill the main context with searches, logs, or file contents.
Our view at MCP Directory is simple: start with one specialist and one job. A read-only reviewer, browser checker, or incident investigator earns its overhead; a generic “do everything” subagent usually duplicates the parent and makes failures harder to trace. If you are still choosing a Claude surface, see the Claude MCP client guide.
How it works today
A Claude Code subagent is a Markdown definition with YAML frontmatter, stored per project in .claude/agents/ or for all projects in ~/.claude/agents/. Claude can delegate automatically from the description, or you can name or @-mention the agent explicitly.
The useful MCP mechanism is the mcpServers field. According to Anthropic’s current scoping reference, each list item can be either a string naming a server already configured in the session or an inline server definition. A string reuses the parent connection; an inline definition connects when the worker starts and disconnects when it finishes.
This creates three practical patterns:
- Inherited tools: the subagent receives MCP tools already available to the parent, subject to its tool restrictions.
- Named reference: adding
- githubundermcpServersshares the configuredgithubconnection. - Inline server: the server exists only for that agent, so its tool descriptions do not occupy the parent’s context.
MCP itself still follows a host-client-server architecture: the host manages permissions and context, while a client maintains a connection to each server. The MCP architecture guide is the cleanest explanation of that boundary. A subagent is not an MCP server and MCP does not create the subagent; Claude Code orchestrates both.
Step-by-step setup
The safest setup is a project-scoped, read-focused agent with one inline server. Use the vendor-documented Playwright example below, then widen access only after the workflow proves useful.
-
Create the agent file. Add
.claude/agents/browser-checker.mdin the repository. Use~/.claude/agents/browser-checker.mdonly if you deliberately want the definition available across projects. -
Add verified frontmatter and instructions. Anthropic’s own example uses Microsoft’s published
@playwright/mcppackage:
---
name: browser-checker
description: Tests web features in a real browser and reports reproducible failures.
mcpServers:
- playwright:
type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
---
Test only the requested flow. Report the URL, steps, observed result, and expected result.
This is an inline stdio server, not a .mcp.json entry. Microsoft’s Playwright MCP repository confirms the package name and notes that Node.js 18 or newer is required.
-
Restart if the directory is new. Claude Code detects files added to an existing agents directory, but Anthropic says a session may need restarting when
~/.claude/agents/did not exist at startup. -
Invoke it explicitly first. Ask:
Use the browser-checker subagent to test the sign-in error state.Explicit invocation makes evaluation easier than hoping automatic delegation triggers. -
Verify the boundary. Use
/mcpto inspect connections, then confirm the parent cannot call the inline Playwright tools after the subagent ends. For session-wide installation and scope choices, follow our guide to adding an MCP server.
Do not paste a token into a committed agent file. For a shared server, configure credentials through the server’s documented authentication flow and reference it by name; Anthropic’s MCP guide also warns that servers fetching external content introduce prompt-injection risk.
Claude Code vs other MCP clients
Claude Code is the clear choice when per-worker MCP isolation matters; the other clients focus on making servers available to a chat or coding agent. They can be excellent MCP hosts, but their official docs do not describe Claude Code-style mcpServers frontmatter for a disposable subagent.
| Client | Main configuration | Local and remote MCP | Per-subagent MCP scope | Approval/control model | Best fit |
|---|---|---|---|---|---|
| Claude Code | .mcp.json, settings, CLI, or .claude/agents/*.md | stdio, HTTP, SSE, WebSocket | Yes, named or inline | Parent permissions plus agent restrictions | Terminal workflows and isolated specialists |
| Claude Desktop | Extensions UI; legacy local JSON also exists | Local extensions and remote connectors | No documented worker scope | App prompts and organization controls | General chat with local or SaaS tools |
| Cursor | .cursor/mcp.json or ~/.cursor/mcp.json | stdio, SSE, Streamable HTTP | No documented worker scope | Per-tool toggles; approval by default | IDE-first coding agent |
| Windsurf/Cascade | Marketplace or ~/.codeium/windsurf/mcp_config.json | stdio, SSE, Streamable HTTP | No documented worker scope | Per-tool toggles; 100-tool active limit | IDE workflows centered on Cascade |
Cursor’s official MCP documentation confirms project/global paths, transports, tool toggles, and default approvals; our Cursor client page covers the practical install flow. Windsurf documents its config path and 100-tool ceiling in the Cascade MCP guide. Claude Desktop now emphasizes one-click desktop extensions, as explained in Anthropic’s setup guide.
The catch most guides skip
Isolation removes context as well as clutter. A normal subagent does not see the parent’s full conversation history or files already read; it starts from a delegation message, its own prompt, applicable project instructions, and a fresh context, so an underspecified handoff produces confident but misaligned work.
MCP adds another failure surface. Inline servers must start and authenticate, remote services can disconnect, tool results may be verbose, and independent workers can race on the same files or external records. Claude Code automatically reconnects HTTP and SSE servers with backoff, but not local stdio processes, according to Anthropic’s connection behavior.
The workaround is disciplined scoping:
- Give the agent one deliverable, explicit acceptance criteria, and the minimum relevant paths.
- Prefer read-only credentials and omit write-capable tools unless the task requires them.
- Keep dependent planning and implementation in one context.
- Run parallel workers only on independent targets; use worktree isolation when separate code edits are truly necessary.
- Ask for a compact evidence report, not a second essay that refills the parent context.
Subagents also cost extra tokens because each worker has its own input and output. Anthropic notes that model selection can route a specialist to a cheaper model, but that does not make delegation free. I would avoid subagents for a one-file fix, an ambiguous product decision, or any task requiring repeated user approval; the coordination tax exceeds the context saved.
What to connect first
Start with one read-oriented system that closes a real information gap, then add a write-capable server only after you trust the workflow. These three picks cover source control, production evidence, and browser behavior without pretending every developer needs the same stack.
-
GitHub MCP Server for review and issue context. GitHub maintains the official open-source server, with repository, issue, pull-request, and code-security toolsets. Give a reviewer subagent read-only access first; do not let an experimental worker merge or modify issues.
-
Sentry MCP for incident investigation. Sentry operates a hosted MCP service that can bring errors and project context into a focused debugging worker. This is a strong subagent job because event searches are noisy, while the parent usually needs only the suspected cause, evidence, and affected release.
-
Playwright MCP for browser verification. Microsoft’s server exposes browser automation through structured accessibility snapshots. Scope it inline to a browser-checker so the parent does not carry browser tool schemas during ordinary coding, and remember the repository itself says CLI plus skills may be more token-efficient for high-throughput coding agents.
Browse the best MCP servers for alternatives, but resist collecting integrations. Three narrowly assigned servers beat twenty overlapping ones: fewer schemas, fewer credentials, clearer approvals, and a much better chance that Claude chooses the right tool.