대부분의 MCP 설정 가이드는 JSON으로 된 거대한 벽으로 시작합니다. 그럴 필요가 없습니다. Claude Code는 단 하나의 CLI 명령어로 MCP 서버를 등록할 수 있으며, 많은 팀에게 필요한 MCP 서버 개수는 0개입니다. 규칙 파일에 있는 셸 명령어만으로도 같은 작업을 수행하며 컨텍스트 오버헤드가 적습니다. 이것이 최소 경로이며, 실제로 디스크에 기록되는 구성이고, '내 서버가 표시되지 않아요'라는 스레드에서 거의 모든 원인을 설명하는 몇 가지 실패 모드를 다룹니다.

두 명령어의 성공적인 경로

로컬 (stdio) 서버의 경우, 전체 설정은 다음과 같습니다:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

그런 다음 세션 내부에서:

/mcp

/mcp는 구성된 모든 서버, 연결 상태, 그리고 노출되는 도구를 보여줍니다. 서버가 목록에 있고 연결되었다면, 끝난 것입니다. 그렇지 않다면, 실패 모드 섹션으로 건너뛰세요. 원인은 거의 항상 네 가지 중 하나입니다.

-- 구분자는 중요합니다. 이 뒤의 모든 것은 Claude Code가 서버 프로세스를 시작하기 위해 실행하는 명령어입니다. 그 앞의 플래그들은 claude mcp add 자체에 속합니다.

스코프: 구성이 실제로 존재하는 곳

모든 MCP 서버는 스코프(scope)를 가지며, 이 스코프가 어떤 파일에 기록될지, 그리고 누가 그것을 볼 수 있는지를 결정합니다. 이것은 대부분의 사람들이 실수로 서버가 관련 없는 프로젝트까지 따라가거나, 원하는 프로젝트에는 따라가지 않을 때 발견하는 부분입니다.

Scope	Flag	Written to	Who sees it
local (default)	—	사용자 구성 파일, 현재 프로젝트에 키 지정	오직 당신만, 이 프로젝트에서만
...

• 팀 전체가 필요로 하는 서버는 .mcp.json에 위치해야 하며, 다른 설정 파일처럼 커밋되어야 합니다. 팀원들은 풀(pull)을 통해 이를 가져갑니다. Claude Code는 각 사용자에게 프로젝트의 서버를 처음 사용할 때 승인하도록 요청합니다 (이것들은 인터넷 관점에서는 임의의 실행 파일입니다). 따라서 아무도 당신이 커밋한 것을 조용히 실행하지 않습니다. 만약 프롬프트를 거부했다가 나중에 마음이 바뀌면, claude mcp reset-project-choices를 다시 실행하여 요청할 수 있습니다.
• 개인 워크플로우에 필요한 서버는 사용자 범위(user scope)에 속해야 하며, 모든 프로젝트의 로컬 범위(local scope)로 복사 붙여넣기 해서는 안 됩니다. claude mcp add --scope user notion ...을 한 번 실행하면 어디서든 사용할 수 있습니다.

.mcp.json은 일반 JSON 파일이므로 직접 편집하기에 좋습니다:

{
  "mcpServers": {
    "github": {
...

여기서 ${GITHUB_TOKEN}는 장식이 아닙니다. Claude Code는 서버 시작 시 .mcp.json의 환경 변수 참조를 확장합니다 (${VAR}, 기본값 설정을 위해 ${VAR:-fallback} 사용). 이것이 바로 누구나 토큰을 커밋하지 않으면서 공유 설정을 커밋하는 방법입니다: 파일은 변수를 참조하고, 각 기기가 자체 값을 제공합니다.

원격 서버 (Remote servers)

로컬 프로세스가 아닌 URL 뒤에 존재하는 서버는 전송(transport) 플래그를 사용합니다:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

인증이 필요한 서비스의 경우, 세션에서 /mcp를 실행하고 서버를 선택하면 됩니다. Claude Code가 브라우저에서 OAuth 흐름을 처리하고 토큰을 저장합니다. 키가 설정 파일에 남지 않는데, 이는 키가 있어서는 안 되는 정확한 위치입니다.

원격 HTTP 서버에는 반드시 이해해야 할 운영 속성이 하나 있습니다: 네트워크와 함께 실패한다는 것입니다. 만약 제공업체의 MCP 엔드포인트가 다운되면, 세션은 복구될 때까지 해당 도구를 잃게 됩니다. 따라서 중요한 것이 항상 MCP 도구가 존재한다고 가정하지 않도록 규칙을 설계하십시오.

실제로 발생하는 네 가지 실패 모드

실제로 발생하는 네 가지 실패 모드

1. 명령어가 Claude Code가 실행되는 PATH에 없습니다. 사용자의 셸은 nvm(Node Version Manager)으로 관리되는 node를 가지고 있지만, Claude Code가 시작된 환경은 그렇지 않을 수 있습니다. 만약 /mcp가 서버 실패로 표시하고 로그에 command not found라고 나온다면, 바이너리에 대한 절대 경로(command: "/Users/you/.nvm/versions/node/v22.17.0/bin/npx")를 사용하거나 환경을 먼저 로드하는 래퍼 스크립트를 사용하십시오.

2. env 블록이 누락되었습니다. stdio 서버는 자식 프로세스(child process)입니다. 즉, 제공되지 않은 것은 아무것도 상속받지 못합니다. 만약 서버가 GITHUB_TOKEN을 필요로 하는데 env 블록에서 이를 전달하지 않으면, 서버는 보통 정상적으로 시작되지만 모든 도구 호출이 인증 오류(auth error)와 함께 실패합니다. 혼란스러운 증상: 연결된 서버, 작동하지 않는 도구.

3. 서버가 시작하는 데 느리고 종료됩니다. Claude Code는 시작 시간 초과(startup timeout)를 강제합니다 (환경 변수 MCP_TIMEOUT으로 설정 가능). 첫 실행 시의 npx 다운로드가 전형적인 원인입니다: 다운로드 시간이 초과보다 길면, 서버가 "실패"하고 두 번째 시도는 패키지가 캐시되었기 때문에 신비롭게 작동합니다. 캐시를 미리 데우거나(npx -y <pkg> --help를 한 번 실행) 시간 초과를 늘리십시오.

4. 서버 문제가 아니라 범위(scope) 문제입니다. 서버는 추가한 프로젝트에서는 작동하지만 다른 곳에서는 "누락"된 것처럼 보입니다. 그 이유는 기본 범위가 로컬이기 때문입니다. claude mcp list는 현재 컨텍스트에서 구성된 것을 보여줍니다. 만약 목록에 서버가 없다면, 그것은 고장 난 것이 아니라 단순히 다른 곳에 있다는 의미입니다.

위의 어떤 경우에도 해당하지 않으면 claude --debug를 실행하십시오. 그러면 조용한 부재 대신 각 서버의 시작과 실제 오류를 기록합니다.

권한(Permissions): MCP 도구는 그저 도구일 뿐입니다

모든 MCP 도구는 mcp__<서버>__<도구> 형태의 이름을 가지며, 사용자의 권한 규칙은 이를 다른 모든 도구와 동일하게 취급합니다. 유용한 두 가지 패턴이 있습니다:

{
  "permissions": {
    "allow": ["mcp__github__search_repositories"]
... 

mcp__github (도구 접미사 없음)는 서버가 노출하는 모든 도구와 일치합니다. 한 가지 알아둘 점은 MCP 도구 규칙이 인자 패턴을 사용하지 않는다는 것입니다. 즉, 도구를 허용하거나 거부할 수는 있지만, '이러한 인자를 가진 이 도구'처럼 지정할 수는 없습니다. 따라서 쓰기 권한이 필요한 토큰(write-capable tokens)의 범위를 적절히 설정해야 합니다. 권한 시스템은 어떤 도구가 실행될지 제어하고, 토큰은 그 도구들이 무엇을 건드릴 수 있을지를 제어합니다.

MCP가 전혀 필요하지 않은 경우

연결된 모든 서버는 자체 도구 정의를 컨텍스트에 주입합니다. 이는 세션 사용 여부와 관계없이 매 요청마다 토큰으로 비용이 발생하는 기능입니다. 따라서 서버를 추가하기 전에, 해당 통합이 실제로 어떤 목적인지 질문해 볼 가치가 있습니다:

• 이미 가지고 있는 CLI(Command Line Interface)를 래핑하는 경우? Claude Code는 Bash를 통해 gh, aws, kubectl, psql 등을 직접 실행할 수 있습니다. 규칙 파일에 한 줄(