GLOSSARY

.mcp.json

중급

이 페이지는 AI 문맥에서 자주 쓰이는 .mcp.json의 뜻과 쓰임을 중급 난이도 기준으로 정리한 AI 용어사전 항목입니다. 정의와 맥락, 관련 용어 5개 순서로 묶었으니, 아래 설명을 먼저 읽고 연결된 개념과 글까지 이어서 보면 이해가 빨라집니다.

.mcp.json은 Claude Code에서 프로젝트 범위의 MCP 서버 연결 설정을 저장하는 JSON 파일입니다. 프로젝트 구성원이 같은 서버 목록을 공유하는 데 쓰이며, 서버 실행 명령이나 원격 접속 정보를 담습니다. 파일을 공유하는 것과 서버 사용을 승인하거나 인증을 마치는 것은 별도 단계이고, 개인별 비밀값도 설정 파일과 나누어 관리합니다.

프로젝트에서 공유하는 서버 목록

2026년 10월 11일 확인한 Claude Code의 MCP 문서는 프로젝트 범위의 설정을 프로젝트 루트의 .mcp.json에 저장한다고 설명합니다. 같은 저장소에서 작업하는 사람이 공통 서버 구성을 전달받는 데 쓰는 파일입니다. 사용자 전체 범위나 특정 컴퓨터의 로컬 범위 설정과는 적용 범위가 다릅니다. 이름이 같아 보이는 서버도 어느 범위에서 등록했는지에 따라 확인할 위치가 달라집니다.

파일의 mcpServers 아래에는 서버 이름별 연결 설정을 둡니다. 로컬 프로그램으로 실행하는 서버에는 command와 args 같은 실행 정보가 들어가고, 원격 서버에는 전송 방식과 url 같은 정보가 들어갑니다. 서버가 제공하는 도구의 구현 코드를 이 파일에 모두 적는 것은 아닙니다. 설정은 Claude Code가 어떤 프로그램을 실행하거나 어느 주소에 연결할지 지정합니다.

프로젝트를 복사해도 로컬 서버 프로그램의 설치나 원격 서비스 계정이 자동으로 준비되지는 않습니다. 구성원이 같은 파일을 받았더라도 필요한 실행기가 없거나 주소에 접근할 권한이 없으면 연결 단계에서 실패합니다. 공유할 설정과 각 환경에서 준비할 의존성을 나누어 설명하면 저장소만으로 복구되는 부분과 추가 준비가 필요한 부분이 드러납니다.

일반 설정 파일과의 역할 구분

Claude Code의 설정 파일 안내는 사용자, 공유 프로젝트, 프로젝트 로컬 설정을 서로 다른 파일과 범위로 구분합니다. .claude/settings.json은 권한이나 훅 등 프로젝트 설정을 공유하는 데 쓰이며, .claude/settings.local.json은 개인의 프로젝트별 설정을 담습니다. .mcp.json을 이런 모든 설정의 통합 파일로 취급하면 올바른 키를 잘못된 위치에 넣게 될 수 있습니다.

MCP는 서버와 클라이언트가 기능과 문맥을 주고받는 프로토콜이고, .mcp.json은 특정 클라이언트 제품에서 그 연결을 설정하는 파일 이름입니다. 다른 MCP 클라이언트가 반드시 같은 위치의 같은 파일을 읽는 것은 아닙니다. 다른 도구용 예제를 옮길 때는 서버가 요구하는 정보와 Claude Code가 읽는 파일 구조를 함께 확인합니다. 프로토콜이 같다는 사실만으로 설정 저장 위치까지 같아지지는 않습니다.

연결 정보가 문법에 맞는 JSON인지와 유효한 서버 구성인지는 따로 확인합니다. 쉼표나 따옴표가 잘못되면 파일을 읽는 단계에서 문제가 나고, 실행 경로나 전송 방식이 맞지 않으면 서버를 준비하거나 연결하는 단계에서 문제가 납니다. 같은 증상을 보더라도 오류가 발생한 단계에 따라 확인할 값이 다릅니다. 파일을 고친 뒤에는 실제로 어떤 서버가 등록되고 연결됐는지 살펴봅니다.

승인과 개인별 인증 정보

MCP의 프로젝트 범위 안내는 대화형 세션에서 프로젝트의 .mcp.json 서버를 사용하기 전에 사용자가 승인하도록 하는 흐름을 설명합니다. 저장소에 파일이 들어 있다는 사실이 그 안의 명령이나 외부 연결을 이미 승인했다는 의미는 아닙니다. 프로젝트에서 제안한 구성과 개인의 실행 판단을 구분하는 단계입니다. 서버를 신뢰할 수 있는지 확인할 때는 실행할 프로그램과 접속 대상을 실제 값으로 봅니다.

같은 문서는 설정 값에서 환경변수를 참조하는 방법도 안내합니다. 서버 주소 같은 공유 정보와 API 키 같은 개인별 값을 분리하면 팀이 같은 파일을 쓰면서 각자의 실행 환경에서 필요한 값을 제공할 수 있습니다. 환경변수를 쓴다는 이유만으로 비밀값이 자동 보관되는 것은 아니므로, 실제 값이 들어간 파일과 출력 기록은 공유 대상에서 구분합니다.

문제 해결에서는 설정 파일이 읽혔는지, 서버가 시작됐는지, 인증이 끝났는지, 필요한 도구를 호출할 수 있는지를 나누어 확인합니다. 서버 목록에 이름이 보이는 것과 실제 작업이 성공하는 것은 다른 단계입니다. 프로젝트 인계에는 공유 파일 위치와 추가 설치 항목, 인증이 필요한 서비스만 남겨도 다음 작업자가 연결을 복구할 범위를 알 수 있습니다. 인증 토큰 자체를 인계 원고에 옮기지는 않습니다.

RELATED TERMS