MCP 도구 응답이 메인 컨텍스트를 "폭발"시키는 문제를, 서브에이전트 격리 + 요약/전문 모드 + 읽기/쓰기 분리로 해결하는 패턴을 정리합니다.
MCP 도구를 메인 에이전트가 직접 호출하면, 도구 응답 전체가 메인 컨텍스트에 그대로 주입됩니다. 이때 문제가 되는 건 크게 2가지입니다.
메인 컨텍스트를 "저장소"로 쓰지 말고, 조회는 별도 컨텍스트(서브에이전트)에서 처리한 뒤 메인에는 요약만 반환합니다.
[메인] "PR #123 확인해줘"
-> spawn
[서브에이전트(별도 컨텍스트)]
-> PR 메타 조회
-> diff 조회
-> 파일 목록 조회
-> 리뷰/체크 상태 조회
-> 노이즈 제거 + 패턴 분석 + 구조화
<- 요약(또는 전문)만 반환
이 패턴은 결국 컨텍스트·토큰 관리의 "progressive disclosure"를 도구 계층으로 내린 버전이라고 보면 이해가 쉽습니다.
조회 전용 서브에이전트에 쓰기 권한을 주면, 프롬프트 인젝션/오작동 시 피해 범위가 커집니다.
Context7 유형의 문서 조회 도구는 기본적으로 "찾기(Resolve)"와 "가져오기(Fetch)"를 분리합니다.
resolveLibraryId로 "이름"을 "정확한 라이브러리 ID"로 해석queryDocs로 "ID + 질문"을 넣어 필요한 문서만 가져오기이 구조는 단순히 문서 조회를 넘어서, 다른 MCP 통합에도 그대로 적용됩니다.
서브에이전트는 이를 "복합 조회"로 한 번에 묶고, 메인에는 변경 요약 + 리스크 포인트 + 다음 액션을 반환합니다.
따라서 "검색(Resolve) → 상세(Read)"로 분리하는 게 토큰/품질 모두에 유리합니다.
여기서 말하는 "upstream"은 MCP 서버 레포가 아니라, Atlassian/GitHub 같은 제품 벤더가 서브에이전트 격리 패턴을 구현한 플러그인을 "공식 배포"하는 경우를 뜻합니다.
기술적으로는 충분히 만들 수 있지만, 실제로는 다음 이유로 공식 제공 동기가 약하거나(혹은 제공해도 난이도가 급격히 올라가거나) 하는 경우가 많습니다.
보완적으로, MCP 자체도 "컨텍스트 교환"까지를 목표로 하고, 컨텍스트 예산 관리(요약/캐싱/복합 조회)는 호스트/미들웨어에서 하도록 열어둔 구조라서, 이 패턴은 벤더의 공식 플러그인보다 사용자/커뮤니티 미들웨어로 구현되는 경우가 많습니다.
이 아이디어는 "MCP로 직접 무언가를 조작"하는 영역보다는, 비정형으로 저장된 정보를 획득(read)하는 모든 MCP 통합의 중간 계층에 특히 잘 맞습니다.
그래서 아래 같은 흐름을 공통 템플릿으로 두고, 각각의 데이터 소스에 맞게 adaptor만 바꿔 끼우는 방식이 유효합니다.
예시(일반형):
핵심은 "서버가 똑똑해지는 것"이 아니라, 중간 계층이 ‘컨텍스트 예산’을 관리하는 것입니다.
아래는 동일한 요청을 "직접 MCP 호출" vs "서브에이전트 경유"로 비교해, 메인 컨텍스트에 주입되는 응답 문자 수를 기준으로 계산한 예시입니다.
| 요청 유형 | 직접 호출(대략) | 서브에이전트(대략) | 절약률 |
|---|---|---|---|
| 문서 조회(예: routing) | 12,800자 | 3,800자 | 70% |
| 문서 조회(예: hooks) | 15,000자 | 3,200자 | 79% |
| 단건 이슈 조회 | 1,200자 | 600자 | 50% |
| 검색 다건(10건) | 12,000자 | 1,100자 | 91% |
| 문서 검색(5건) | 3,000자 | 2,000자 | 33% |
| PR 메타 요약 | 14,500자 | 2,500자 | 83% |
| PR diff(대형) | 30,000자 | 3,500자 | 88% |
| PR 복합 조회(메타+diff+files) | 59,500자 | 3,500자 | 94% |
핵심 인사이트:
"툴 출력이 길어져서 컨텍스트가 오염"되는 문제는, 아예 스크립트/MCP 결과를 파일로 빼는 패턴(스크립트/MCP offloading)과 같이 쓰면 더 크게 줄일 수 있습니다.
아래는 이 아이디어를 "가장 단순한 형태"로 구현하는 샘플 구조입니다. 특정 벤더/사내 명칭에 의존하지 않도록, 완전한 일반형 이름으로 작성했습니다.
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
핵심은 4개 레이어입니다.
plugin.json: MCP 서버 연결(transport + auth)commands/*.md: 슬래시 명령 UXskills/*/SKILL.md: 자동 트리거(라우팅) 규칙agents/*.md: 실제 호출/정제 로직(서브에이전트).claude-plugin/plugin.json 샘플 (서버 연결){
"name": "acme-github-plugin",
"description": "Read-only GitHub 조회를 서브에이전트로 격리",
"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": "문서 조회를 서브에이전트로 격리",
"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}"
]
}
}
}
샘플은 구조만 보여줍니다. API 키/토큰은 코드/문서에 하드코딩하지 말고 환경변수로만 주입하는 쪽이 안전합니다.
commands/*.md 샘플 (슬래시 명령)plugins/acme-github/commands/pr.md
---
description: GitHub PR을 서브에이전트로 조회
argument-hint: <owner/repo> <pr-number> [query]
---
# /acme-github:pr
GitHub PR을 서브에이전트로 조회하여 메인 컨텍스트를 절약한다.
## 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 샘플 (자동 트리거 + 위임)plugins/acme-github/skills/github-lookup/SKILL.md
---
name: github-lookup
description: GitHub PR/이슈/레포 조회가 필요할 때 자동 활성화. PR URL, PR #번호, owner/repo 언급에 트리거된다.
---
GitHub 관련 조회가 감지되면, `github-researcher` 서브에이전트를 스폰하여 별도 컨텍스트에서 조회한다.
메인 컨텍스트에는 요약만 반환한다.
## Guidelines
- 항상 서브에이전트를 통해 조회 (메인 컨텍스트에서 직접 MCP 호출 금지)
- PR diff는 기본적으로 요약만 전달 (원문이 필요한 경우에만 detail 모드)
- 쓰기 작업(PR 코멘트/머지/라벨 변경 등)은 메인 에이전트가 직접 수행
agents/*.md 샘플 (서브에이전트 시스템 프롬프트)plugins/acme-github/agents/github-researcher.md
---
name: github-researcher
description: GitHub PR/이슈/레포 정보를 별도 컨텍스트에서 조회하고 요약만 반환하는 경량 에이전트
model: sonnet
---
## Goals
- "요약 모드"에서는 메인 컨텍스트에 주입될 출력량을 최소화한다.
- "전문 모드"에서는 코드리뷰/구현을 위해 필요한 원문을 코드블록으로 제공한다.
## Allowed tools
- `mcp__acme-github__*` 접두사 도구만 사용
- 다른 접두사 도구 호출 금지
## Response modes
### summary (기본)
- PR/이슈 핵심 메타 + 변경 요약(5문장 이내) + 리스크 포인트 + 다음 액션
- 도구 호출 한도: 최대 5회
### detail
- PR body 원문(필요 시)
- diff 원문: ```diff 코드블록으로 반환 (대형 PR이면 상위 N개 파일만)
- 도구 호출 한도: 최대 8회
## Hard rules
- 쓰기 작업(코멘트 작성/머지/상태 변경) 절대 금지
- 실패 시 재시도 금지(인증/연결/권한 문제는 안내만)
메인 에이전트는 서브에이전트에 "질문"이 아니라 **작업 계약(입력/출력/제약)**을 줘야 안정적으로 굴러갑니다.
[REQUEST]
- 대상: org/repo PR #123
- 질문: 변경 요약 + 위험 포인트 + CI 상태 + 미해결 리뷰 코멘트
- 모드: summary
- 제약: 읽기 전용, 최대 5회 MCP 호출, 노이즈 필드(URL 메타 등) 제거
- 출력: 1) 요약 2) 리스크 3) 다음 액션(체크리스트)
"프롬프트/스킬/명령"은 UX이고, 진짜 핵심은
agents/*.md의 가드레일(권한/도구 prefix/호출한도/모드) 입니다.