서브 에이전트는 부모 세션에 없는 MCP 서버를 가질 수 있다

"Claude 에이전트 팀을 어떻게 만들까"에 대한 Anthropic의 답은 프레임워크가 아니라 프리미티브를 쌓아 올리는 사다리에 가깝다. 그중 처음으로 실질적인 쓸모가 생기는 단은 부모 세션이 전혀 건드리지 않는 MCP 서버를 품을 수 있는 서브 에이전트다.

mcpServers가 Claude Code 서브 에이전트에 해주는 일

Claude Code 서브 에이전트는 frontmatter에서 자체 MCP 서버를 선언할 수 있고, 부모 세션은 이를 로드하지 않는다. Anthropic의 서브 에이전트 문서에 따르면, 서브 에이전트의 mcpServers 필드에 있는 인라인 서버는 서브 에이전트가 시작될 때 연결되고 종료될 때 연결이 끊어진다 . 덕분에 서버의 도구 설명과 토큰 오버헤드는 메인 대화의 컨텍스트 창에 들어오지 않는다. 부모는 가볍게 유지되고, 전문 에이전트만 필요한 장비를 갖춘다.

서버를 나열하는 방식은 두 가지다. 인라인 항목은 서브 에이전트 실행 범위에 묶인 새 연결을 띄우고, 문자열 참조는 새 프로세스를 시작하지 않고 이미 이름이 지정된 세션 연결을 재사용한다 . 나머지 정의는 의도적으로 단순하다. 서브 에이전트는 .claude/agents/ 안의 Markdown 파일이며, 필수 항목은 name과 description뿐이다. 그 외의 mcpServers, tools, disallowedTools, model, permissionMode, maxTurns는 모두 선택 사항이다 .

Anthropic의 대표 예시는 인라인 Playwright MCP 서버와 참조된 GitHub 서버를 부여받은 browser-tester 서브 에이전트다. Playwright를 인라인으로 정의하면 해당 도구 설명은 부모 컨텍스트 밖에 두면서도, 서브 에이전트에는 브라우저 제어 권한을 그대로 넘길 수 있다 . 관계는 이렇게 쉽게 모델링할 수 있다. 부모의 서버 목록은 비어 있고, 서브 에이전트는 자체 서버를 들고 있다.

from dataclasses import dataclass


@dataclass(frozen=True)
class MCPServer:
    name: str


@dataclass(frozen=True)
class Session:
    name: str
    mcp_servers: tuple[MCPServer, ...] = ()


parent = Session("parent")
sub_agent = Session("sub-agent", (MCPServer("private-filesystem"),))

print(f"{parent.name} MCP servers: {[s.name for s in parent.mcp_servers]}")
print(f"{sub_agent.name} MCP servers: {[s.name for s in sub_agent.mcp_servers]}")

assert not parent.mcp_servers
assert sub_agent.mcp_servers[0] not in parent.mcp_servers

이 스니펫은 작은 설명용 모델이다. 실행이 확인되었고, 부모 목록은 비어 있으며 서브 에이전트에는 ['private-filesystem']이 출력된다. 실제 Claude Code 내부 구현은 아니지만, mcpServers 필드가 제공하는 격리를 정확히 보여준다.

서브 에이전트 정의 만들기: mcpServers, tools, disallowedTools

서브 에이전트는 YAML frontmatter가 있는 단일 Markdown 파일이다. 프로젝트 범위라면 .claude/agents/<name>.md에, 사용자 범위라면 ~/.claude/agents/<name>.md에 두면 된다. 필수 항목은 name과 description뿐이다 . 이름이 충돌하면 프로젝트 정의가 사용자 정의보다 우선하며, 전체 해석 순서는 관리형 설정 → --agents CLI → 프로젝트 → 사용자 → 플러그인 순서다 .

도구 풀은 frontmatter 필드 두 개로 제어한다. tools는 allowlist다. 나열한 도구만 접근할 수 있다. disallowedTools는 서브 에이전트가 원래 상속받았을 도구를 제거하는 denylist다 . 두 필드 모두 MCP 서버 수준 패턴을 받는다. mcp__<server>는 서버 하나를 가리키고, mcp__<server>__*는 해당 서버의 모든 도구와 일치하며, mcp__*는 모든 MCP 서버를 한 항목으로 허용하거나 취소한다 . 부모에게 없는 서버를 추가하려면 이를 mcpServers와 함께 쓰고, 권한이 넓어지지 않도록 tools를 좁게 잡는다.

description 필드는 장식이 아니다. 자동 위임을 좌우한다. Claude는 이 값을 읽고 들어온 작업을 어떤 서브 에이전트에 보낼지 맞추므로, 막연한 요약 대신 여기로 라우팅하고 싶은 작업의 트리거 키워드를 명확히 써야 한다 .

그 밖의 선택 frontmatter는 폭이 넓다. mcpServers(인라인 객체 또는 문자열 참조), tools, disallowedTools, model(부모와 맞추려면 inherit 사용), permissionMode, maxTurns, hooks, skills, memory, background, isolation, color를 둘 수 있다 . 표면적은 작게 유지하는 편이 좋다. 문서에서도 모든 작업을 전용 에이전트로 만들지 말라고 주의한다. 선택지가 많아질수록 위임 정확도가 떨어지기 때문이다 .

깨지는 지점: 에이전트 팀은 하위 에이전트의 MCP 할당을 물려받지 않습니다

에이전트 팀은 한 단계 다른 계층이며, 에이전트별 인라인 MCP 라우팅은 이 계층으로 넘어가도 유지되지 않습니다. settings.json 또는 환경 변수에 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 설정해 실험적 계층을 활성화합니다 . 하나의 세션이 변경 불가능한 리드가 되어 팀원을 생성합니다. 각 팀원은 자체 컨텍스트 창을 가진 완전히 독립적인 Claude Code 세션이며, 공유 작업 목록과 피어 투 피어 메일박스를 통해 조율합니다. 메인 에이전트에게 다시 보고하는 세션 내부 대리자가 아닙니다 .

문제는 여기에 있습니다. .claude/agents/ 정의를 팀원으로 재사용하면 그 안의 tools 허용 목록과 model은 적용되지만, mcpServers와 skills 프런트매터는 적용되지 않습니다. 팀원은 일반 세션처럼 프로젝트 및 사용자 설정에서 MCP 서버를 로드하고, 여기에 CLAUDE.md 컨텍스트를 더합니다. 리드의 대화 기록은 상속하지 않습니다 .

실무적 결론은 이렇습니다. 하위 에이전트 경로에 작성한 인라인 mcpServers 필드는 하위 에이전트와 메인 스레드 --agent에서만 작동하는 기능입니다. 전체 피어 팀 계층은 개별 에이전트 프런트매터가 아니라 .mcp.json을 읽습니다. 이는 v2.1.219(2026년 7월 24일) 기준으로 확인된 제한입니다 . 팀원에게 비공개 MCP 서버가 필요하다면 에이전트 파일이 아니라 프로젝트 또는 사용자 범위에 넣으세요.

2026년 7월 현재 팀 계층에서 고려해야 할 다른 제한도 있습니다. 진행 중인 팀원 세션 재개 불가, 세션당 팀 하나만 가능, 중첩 팀 불가, 고정된 리드, 생성 시 팀원별 권한 모드 지정 불가입니다 . 또한 하위 에이전트는 v2.1.198(2026년 7월 1일)부터 기본적으로 백그라운드 실행으로 바뀌었기 때문에 이전 릴리스와 동작이 다릅니다 .

허용 목록 와일드카드와 팀 조율: 다음에 시도할 것

큰 MCP 서버에서 단일 도구만 노출하고 나머지는 허용하지 않으려면 좁은 tools 허용 목록과 와일드카드 차단 목록을 함께 사용합니다. disallowedTools의 mcp__<server>__* 패턴은 서버 계열 전체를 한 번에 제거하므로, 특정 도구 하나만 허용하고 그 서버가 제공하는 나머지는 모두 막을 수 있습니다 . 이렇게 하면 업스트림 서버가 검토하지 않은 도구를 추가하더라도 최소 권한을 유지할 수 있습니다.

지연 MCP 도구 로딩은 기본적으로 켜져 있습니다. 시작 시에는 도구 이름과 서버 지침만 로드되고, 전체 스키마는 필요할 때 해석됩니다. 임계값 제어에는 ENABLE_TOOL_SEARCH=auto:N을 설정합니다. tool_reference 블록은 Sonnet 4.5, Haiku 4.5, Opus 4.5 또는 그 이후 버전이 필요합니다 . 그래서 하위 에이전트가 많은 MCP 도구를 갖고도 컨텍스트를 불필요하게 키우지 않을 수 있습니다.

에이전트 팀으로 옮긴다면 조율은 에이전트별 MCP 연결이 아니라 두 가지 기본 요소로 이루어집니다. 의존성 추적이 포함된 공유 작업 목록(대기 / 진행 중 / 완료)과 직접 피어 메시징용 메일박스입니다. 팀원은 리드의 지시를 기다리는 대신 막히지 않은 다음 작업을 스스로 가져갑니다 .

Anthropic이 권장하는 상한은 팀원 3~5명, 각 팀원당 작업 약 5~6개입니다. 그리고 모든 팀원이 별도의 Claude 인스턴스이므로 토큰 비용은 팀 규모에 거의 선형으로 증가합니다 . 핵심은 이렇습니다. 순차 작업이나 단일 파일 작업에는 자체 mcpServers를 가진 Markdown 하위 에이전트가 더 저렴하고 안정적인 경로입니다. 팀은 정말로 병렬적이고 여러 관점이 필요한 작업에 남겨두세요.

자주 묻는 질문

Claude Code 하위 에이전트가 부모의 .mcp.json에 없는 MCP 서버를 사용할 수 있나요?

예. .claude/agents/*.md 파일의 mcpServers 프런트매터 필드는 인라인 서버 설정을 정의할 수 있습니다. 이 서버는 하위 에이전트가 시작될 때 연결되고 끝나면 연결 해제됩니다. 또는 문자열로 기존 이름 있는 연결을 참조해 세션의 활성 연결을 재사용할 수도 있습니다 . 부모 세션은 해당 도구 설명을 로드하지 않으므로, 하위 에이전트는 부모에게 전혀 없는 서버도 보유할 수 있습니다.

하위 에이전트 정의에서 tools와 disallowedTools는 어떻게 다른가요?

tools는 허용 목록입니다. 목록에 적은 도구만 하위 에이전트가 사용할 수 있고, 나머지는 모두 제공되지 않습니다. disallowedTools는 차단 목록입니다. 이름을 지정한 도구를 제외한 모든 상속 도구를 사용할 수 있습니다 . 둘 다 mcp__<server>, mcp__<server>__*, mcp__* 같은 MCP 패턴을 받으므로, 한 항목으로 서버 계열 전체를 허용하거나 제거할 수 있습니다.

에이전트 팀의 팀원은 하위 에이전트 파일에 정의된 mcpServers를 받나요?

아니요. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 아래에서 하위 에이전트 정의를 팀원으로 재사용하면 tools 허용 목록과 model은 적용되지만, mcpServers와 skills 프런트매터는 무시됩니다 . 팀원은 일반 세션과 정확히 같은 방식으로 프로젝트 및 사용자 설정에서 MCP 서버를 로드하므로, 에이전트별 인라인 MCP 라우팅은 팀으로 이어지지 않습니다.

description 필드는 어떤 작업이 하위 에이전트로 라우팅될지 어떻게 제어하나요?

Claude는 description 필드를 읽고 들어오는 작업을 자동 위임에 적합한 하위 에이전트와 매칭합니다 . 그곳에 보내고 싶은 작업 이름을 명시적인 트리거 키워드로 채우세요. 표현이 구체적일수록 라우팅이 더 안정적입니다. 문서는 모든 것을 전용 에이전트로 만들지 말라고도 경고합니다. 선택지가 많아질수록 위임 정확도가 떨어지기 때문입니다.

하위 에이전트의 인라인 MCP 서버가 부모 세션의 컨텍스트 창에 영향을 주나요?

아니요. 바로 그것이 구조적 핵심입니다. Anthropic 문서의 browser-tester 예시에서는 Playwright 서버를 인라인으로 정의해, 하위 에이전트에는 장착하면서도 해당 도구 설명이 부모 컨텍스트에 들어가지 않게 합니다 . 이를 통해 메인 세션에 토큰 부담을 더하지 않고도 한 작업자에게 특화된 프로토콜 계층을 붙일 수 있습니다.

이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.

구독하기