This page summarizes a pattern to prevent MCP tool outputs from "flooding" your main context window, using subagent isolation + summary/detail modes + read/write separation.
When the main agent calls MCP tools directly, the full tool response is injected into the main context window. This typically causes two problems:
Instead of using the main context as a "storage", delegate read operations to a subagent running in an isolated context, and return only a distilled result to the main context.
[Main] "Check PR #123"
-> spawn
[Subagent (isolated context)]
-> Fetch PR metadata
-> Fetch diff
-> Fetch file list
-> Fetch review/comments/status
-> De-noise + pattern analysis + structuring
<- Return summary (or full text) only
You can think of this as applying the "progressive disclosure" principle from Context & token management (Korean) to the tool layer.
Giving write capability to a lookup-only subagent increases the blast radius of prompt injection / unintended actions.
Context7-style documentation lookup tools typically separate "Resolve" and "Fetch":
resolveLibraryId turns a fuzzy name into a precise library IDqueryDocs fetches only what you need using "ID + question"This is not just for docs; the same idea generalizes to other MCP integrations.
A subagent bundles these into a single "composite lookup" and returns change summary + risk points + next actions.
So "Resolve (search) -> Fetch (read detail)" tends to be better for both tokens and quality.
Here, "upstream" does not mean MCP server repositories. It means a product vendor (e.g., Atlassian/GitHub) shipping an official plugin that implements the subagent-isolation pattern.
It is technically feasible, but official distribution often has weak incentives and a much higher maintenance and responsibility burden:
Complementarily, MCP intentionally focuses on context exchange while leaving context-budget management (summary/caching/composite lookups) to hosts and middleware, so this pattern often appears in user/community middleware rather than vendor-official plugins.
This idea is especially suitable not for "direct manipulation" (write/actuation) MCPs, but for any MCP integration whose main purpose is retrieving unstructured information.
A useful shared template is:
Generic examples:
The point is not to make the server smarter; it's to have middleware that manages the context budget.
The table below is an example of comparing response characters injected into the main context for "direct MCP calls" vs "subagent-mediated" calls.
| Request type | Direct MCP (approx) | Subagent (approx) | Savings |
|---|---|---|---|
| Docs lookup (routing) | 12,800 chars | 3,800 chars | 70% |
| Docs lookup (hooks) | 15,000 chars | 3,200 chars | 79% |
| Single issue lookup | 1,200 chars | 600 chars | 50% |
| Search (10 results) | 12,000 chars | 1,100 chars | 91% |
| Doc search (5 results) | 3,000 chars | 2,000 chars | 33% |
| PR summary | 14,500 chars | 2,500 chars | 83% |
| PR diff (large) | 30,000 chars | 3,500 chars | 88% |
| Composite PR lookup | 59,500 chars | 3,500 chars | 94% |
Key insight:
If the real problem is huge outputs, combining this with a "script/MCP offloading" approach (see Script/MCP offloading (Korean)) helps even more.
Below is a minimal, vendor-neutral sample layout showing how to express this idea.
mcp-subagent-plugins/
.claude-plugin/
marketplace.json
plugins/
acme-context7/
.claude-plugin/plugin.json
commands/docs.md
skills/context-docs/SKILL.md
agents/docs-researcher.md
acme-github/
.claude-plugin/plugin.json
commands/pr.md
skills/github-lookup/SKILL.md
agents/github-researcher.md
acme-atlassian/
.claude-plugin/plugin.json
commands/jira.md
commands/confluence.md
skills/jira-lookup/SKILL.md
skills/confluence-lookup/SKILL.md
agents/jira-researcher.md
agents/confluence-researcher.md
Four layers matter:
plugin.json: server connection (transport + auth)commands/*.md: slash-command UXskills/*/SKILL.md: auto triggers (routing)agents/*.md: actual chaining/distillation logic (subagent).claude-plugin/plugin.json sample (server connection){
"name": "acme-github-plugin",
"description": "Isolate read-only GitHub lookups via subagents",
"version": "1.0.0",
"mcpServers": {
"acme-github": {
"type": "http",
"url": "https://your-mcp-github.example.com/mcp",
"headers": {
"Authorization": "Bearer ${GITHUB_TOKEN}",
"Content-Type": "application/json"
}
}
}
}
{
"name": "acme-context7-plugin",
"description": "Isolate docs lookup via subagents",
"version": "1.0.0",
"mcpServers": {
"acme-context7": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"your-context7-image:latest",
"node",
"dist/index.js",
"--transport",
"stdio",
"--api-key",
"${CONTEXT7_API_KEY}"
]
}
}
}
Do not hardcode tokens/keys in repo docs. Inject only via environment variables.
commands/*.md sample (slash command)plugins/acme-github/commands/pr.md
---
description: Look up a GitHub PR via a subagent
argument-hint: <owner/repo> <pr-number> [query]
---
# /acme-github:pr
Look up a GitHub PR via a subagent to save the main context window.
## Usage
/acme-github:pr <owner/repo> [query]
## How It Works
1. Spawns a `github-researcher` subagent in a separate context
2. The subagent fetches PR details, diff, and reviews via MCP
3. Returns a concise summary to the main context
skills/*/SKILL.md sample (auto trigger + delegation)plugins/acme-github/skills/github-lookup/SKILL.md
---
name: github-lookup
description: Auto-activate when GitHub PR/issue/repo lookups are needed (PR URLs, #numbers, owner/repo mentions)
---
When GitHub lookup intent is detected, spawn `github-researcher` in an isolated context and return only a summary to the main context.
## Guidelines
- Never call MCP tools directly from the main context
- Default to summary-only for diffs; use detail mode only when raw text is required
- Any write actions (comments/merge/labels) must be executed by the main agent
agents/*.md sample (subagent system prompt)plugins/acme-github/agents/github-researcher.md
---
name: github-researcher
description: Lightweight subagent that reads GitHub PR/issue/repo data in an isolated context
model: sonnet
---
## Goals
- In summary mode: minimize output injected into the main context
- In detail mode: include necessary raw text for review/implementation
## Allowed tools
- Only tools with prefix `mcp__acme-github__*`
- Forbid other prefixes
## Response modes
### summary (default)
- core metadata + change summary (<= 5 sentences) + risk points + next actions
- tool-call cap: max 5 calls
### detail
- raw body where needed
- raw diff inside a ```diff code block (for large PRs, include top-N files)
- tool-call cap: max 8 calls
## Hard rules
- Never perform write actions (comments/merge/state changes)
- On failure, provide guidance; do not retry in loops
Subagents behave best when you pass an explicit contract:
[REQUEST]
- Target: org/repo PR #123
- Ask: summary + risk points + CI status + unresolved review comments
- Mode: summary
- Constraints: read-only, <= 5 MCP calls, remove noisy fields (URL metadata, etc.)
- Output: (1) Summary (2) Risks (3) Next actions (checklist)
Commands/skills are UX. The real core is guardrails inside
agents/*.md(privileges, tool prefix allowlists, call limits, modes).