Claude Code Subagent MCP Scope Guide

Why This Matters

Subagents are useful when a side task would fill the main conversation with logs, search output, or temporary context. The risk is that a broad subagent can inherit more authority than the task needs. The better pattern is to design each subagent as a small operating surface: one job, a clear model choice, explicit tool access, and only the MCP servers it needs.

Claude Code supports subagent files with frontmatter, explicit tool lists, disallowed tools, permission modes, scoped MCP servers, hooks, persistent memory, and optional worktree isolation. MCP itself has different transport and auth models, so local stdio servers and remote HTTP servers need different handling. This guide turns those pieces into a practical setup checklist.

Recommended Design Flow

1. Name the job before naming the agent. A good description tells Claude when to delegate. Write the description around the trigger condition, not the personified role. "Use after dependency changes to check lockfile and license risk" is easier to route than "dependency expert".

2. Start read-only. For review, research, source lookup, and duplicate detection, give the subagent read-only tools first. Add write or shell access only when the subagent has a specific implementation duty.

3. Scope MCP servers to the task. If the subagent only researches docs, give it a documentation MCP server. If it checks GitHub metadata, give it GitHub access. Do not attach Slack, browser, database, and issue-tracker servers to a generic worker just because they are configured globally.

4. Choose transport deliberately. Stdio MCP servers run as local child processes and usually receive secrets through environment variables. Remote HTTP servers may require OAuth, bearer tokens, and resource-bound access. Keep those risks separate in your setup notes.

5. Use worktree isolation for patching workers. If a subagent may edit files, worktree isolation prevents it from writing directly into the parent session's current checkout. Review the patch before merging it back.

6. Treat memory as a data store. Persistent memory is useful for recurring project patterns, but it should not collect secrets, customer names, private tickets, or one-off incident data.

Example Subagent Shape

---
name: docs-mcp-reviewer
description: Review source-backed docs claims and cite official URLs before content changes are merged.
tools: Read, Glob, Grep
mcpServers:
  docs-search:
    command: npx
    args: ["-y", "@example/docs-mcp"]
model: sonnet
isolation: worktree
---
Review the proposed content for source support, stale claims, duplicate risk,
and privacy notes. Return only findings with source URLs and suggested edits.

MCP Boundary Checklist

• The subagent has one primary task and a narrow routing description.
• Tool access is explicit; read-only workers do not inherit write tools.
• Each MCP server is justified by the task and omitted when not required.
• Stdio servers receive credentials from environment variables, not hardcoded config.
• Remote HTTP servers use HTTPS and resource-bound tokens where the server supports OAuth.
• Hooks are documented so maintainers know what runs before or after subagent work.
• Persistent memory is disabled unless the workflow needs cross-session learning.
• The first run uses a small non-sensitive test case.

Troubleshooting

The subagent does not get selected

Tighten the description around the exact task and use an explicit invocation once or twice. If two subagents claim the same task, make one description narrower.

The subagent sees too much data

Remove inherited tools, omit unrelated MCP servers, and turn off persistent memory. For repository work, prefer worktree isolation and read-only tooling.

The MCP server works in the main session but not the subagent

Check whether the server is configured at a scope the subagent can see. Inline server definitions in subagent frontmatter are useful for project-specific servers, but plugin subagents may ignore some security-sensitive fields.

Duplicate Check

Existing guides cover MCP setup, least privilege, safe hooks, and code review workflows. This entry focuses on the narrower Claude Code pattern of scoping MCP servers and permissions inside custom subagents.

References

• Claude Code subagents - https://code.claude.com/docs/en/sub-agents
• Claude Code hooks - https://code.claude.com/docs/en/hooks
• MCP transports - https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
• MCP authorization - https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization