.mcp.json 완전 해부 — 서브에이전트에 새 도구를 연결하는 방법

서브에이전트의 tools 필드에는 기본 도구(Read, Edit, Bash, Grep)를 지정한다. 그런데 이 기본 도구만으로 커버되지 않는 능력이 필요할 때가 있다. 웹 페이지를 직접 가져오거나, 가설을 단계별로 구조화해서 추론하거나, 외부 API를 호출하거나. 이런 새 도구는 MCP 서버에서 온다. 어떤 MCP 서버를 쓸지를 정의하는 파일이 .mcp.json이다.

MCP(Model Context Protocol)는 AI 모델이 외부 시스템·도구를 표준 방식으로 호출하는 프로토콜이다 — USB-C처럼 다양한 장치를 하나의 표준 포트로 연결하는 것과 같다.

.mcp.json이 없을 때 vs 있을 때

▲ .mcp.json 없음 — 기본 도구만, 외부 능력 없음

▲ .mcp.json 있음 — MCP 도구로 외부 능력 확장

.mcp.json의 위치

파일 구조 — debug-pack의 실제 .mcp.json

{
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  },
  "fetch": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-fetch"]
  }
}

최상위 키 이름이 서버 이름이 된다. 이 이름이 에이전트 파일의 tools 필드에서 mcp__서버이름__도구이름 형식으로 참조된다.

정리 — .mcp.json의 4가지 핵심 규칙

여기까지 보면 ".mcp.json에 무엇이 있고 무엇이 없는지", "이름은 어디서 정해지는지"가 헷갈리기 쉽다. 네 가지로 정리한다.

(a) 서버만 적고, 도구는 동적 발견된다

.mcp.json에는 도구 이름 칸이 없다. 서버를 띄운 뒤 클라이언트가 표준 호출(tools/list)로 물어보면 서버가 자기가 노출하는 도구 목록을 돌려준다. 그래서 서버 버전이 올라가며 도구가 추가·삭제돼도 설정 파일은 그대로 둘 수 있다 — 동적 발견이 정적 등록을 대체한다.

(b) 최상위 JSON 키는 사용자가 정하는 클라이언트 별칭이다

최상위 키는 "이 클라이언트가 이 서버를 뭐라고 부를지" 정하는 핸들이다. 사용자가 자유롭게 정할 수 있다. 보통 패키지 이름과 맞추는 게 관례지만 강제는 아니다. MCP 프로토콜 자체에는 별개로 "서버가 스스로 부르는 이름"(initialize 응답의 serverInfo.name)이 있지만, 클라이언트는 그것을 무시하고 JSON 키만으로 도구 ID를 합성한다.

(c) 도구 ID는 mcp__<JSON키>__<도구이름> 으로 합성된다

JSON 키(sequential-thinking)와 서버가 실제로 노출하는 함수 이름(sequentialthinking)은 별개의 것이다. 두 토큰이 우연히 거의 같아서 한 가지처럼 보일 뿐이다. 한 서버가 도구 N개를 노출하면 같은 JSON 키 아래 도구 ID N개가 만들어진다 — 예를 들어 GitHub MCP 서버는 mcp__github__list_issues, mcp__github__create_pull_request처럼 같은 접두사 아래 수십 개를 노출한다.

(d) 플러그인 형식과 일반 설정 형식이 다르다

지금까지 본 예제는 플러그인 루트의 .mcp.json 형식이다 — wrapper 없이 서버 맵을 최상위에 바로 적는다.

{
  "sequential-thinking": { "command": "npx", "args": [...] },
  "fetch":               { "command": "npx", "args": [...] }
}

일반 Claude Code 설정 파일(~/.claude.json, 프로젝트 루트의 .mcp.json)에서는 "mcpServers" 키로 한 번 감싼다.

{
  "mcpServers": {
    "sequential-thinking": { "command": "npx", "args": [...] },
    "fetch":               { "command": "npx", "args": [...] }
  }
}

형식만 다르고 의미("MCP 서버 N개 등록")는 동일하다. 다른 글에서 본 예제와 모양이 달라도 당황하지 말 것 — 플러그인 안인지 일반 설정인지 위치만 확인하면 된다.

MCP 서버 실행 패턴 3가지

▲ 패턴 1: npx — npm 패키지 (가장 흔함)

▲ 패턴 2: uvx — Python 패키지

▲ 패턴 3: 로컬 스크립트 — 직접 만든 MCP 서버

.mcp.json과 에이전트 파일의 두 단계 연결

두 파일이 모두 동의해야 도구가 활성화된다. .mcp.json이 "이 서버를 sequential-thinking이라는 이름으로 등록한다"고 선언하고, 에이전트 파일이 "sequential-thinking 서버의 sequentialthinking 도구를 허용한다"고 선언할 때 비로소 에이전트가 그 도구를 쓸 수 있다. 이름 대소문자와 하이픈·언더스코어를 정확히 일치시켜야 한다.

도구 이름 조합 규칙

env 필드 — 환경 변수 전달

언제 .mcp.json이 필요한가

.mcp.json은 선택 사항이다. 에이전트가 기본 도구(Read, Edit, Bash, Grep, Glob)만 쓴다면 이 파일 자체가 필요 없다. 기본 도구의 경계를 넘어설 때 비로소 .mcp.json을 추가하고 적절한 MCP 서버를 연결하면 된다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.