Claude Code MCP: 서버 추가 방법과 설정이 저장되는 곳

Claude Code에 MCP 서버를 추가하는 방법

1. 트랜스포트 고르기

   클라우드에서 호스팅되는 원격 서버에는 HTTP를 쓰세요. 권장 트랜스포트이고, 서버가 지원 중단된 SSE 트랜스포트만 제공하면 Claude Code가 SSE로 대체해요. 로컬 프로세스로 실행되는 서버에는 stdio를 쓰세요. stdio에서는 -- 뒤의 내용이 모두 그대로 서버에 전달돼요.

   # Remote HTTP server (recommended for cloud services)
   claude mcp add --transport http notion https://mcp.notion.com/mcp
   
   # With a bearer token
   claude mcp add --transport http secure-api https://api.example.com/mcp \
     --header "Authorization: Bearer your-token"
   
   # Local stdio server: everything after -- is the server's own command
   claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
     -- npx -y airtable-mcp-server

2. 스코프 고르기

   --scope를 붙이지 않으면 서버는 local 스코프예요. 나만, 이 프로젝트에서만 쓴다는 뜻이에요. --scope project를 붙이면 팀용으로 .mcp.json에 기록되고, --scope user를 붙이면 내 모든 프로젝트에서 쓸 수 있어요. 아래 표를 참고하세요.

3. 필요하면 로그인하기

   원격 서버는 OAuth를 쓰는 경우가 많아요. Claude Code 안에서 /mcp를 실행해 인증할 서버를 고르거나, 셸에서 claude mcp login <name>을 실행하세요. 헤드리스 -p 실행에서는 로그인 흐름을 열 수 없으니 먼저 대화형으로 로그인해 두세요.

4. 연결됐는지 확인하기

   /mcp로 서버별 상태와 도구를 확인하고, 셸에서는 claude mcp list를 실행하세요. 그런 다음 Claude에게 도구 이름을 말해 사용해 달라고 하세요.

5. 서버 관리하기

   명령줄에서 서버를 나열하고, 자세히 보고, 제거하거나 가져올 수 있어요. 자주 안 쓰는 서버는 제거하는 대신 /mcp에서 비활성화하세요.

   claude mcp list            # every configured server
   claude mcp get notion      # one server's details
   claude mcp remove notion   # remove it (run claude mcp logout notion first to revoke tokens)
   claude mcp add-from-claude-desktop   # import from Claude Desktop (macOS, WSL)

출처: Claude Code 문서, Connect Claude Code to tools via MCP

MCP 스코프와 설정 파일 위치

Claude Code는 MCP 설정을 여기에 저장해요. MCP의 local 스코프는 .claude/settings.local.json이 아니라 ~/.claude.json에 저장된다는 점에 주의하세요.

.mcp.json으로 서버 공유하기

.mcp.json을 쓰면 팀 전체가 같은 서버를 쓸 수 있어요. 비밀 값은 환경 변수로 파일 밖에 두세요. ${VAR}는 변수 값으로 확장되고, ${VAR:-default}는 변수가 설정되지 않았을 때 기본값을 써요. 확장은 command, args, env, url, headers에서 동작해요.

1. 비밀 값 대신 변수를 참조하기

   Claude Code는 .mcp.json의 프로젝트 서버를 처음 쓸 때 사람마다 승인을 받아요. claude mcp reset-project-choices로 그 선택을 초기화할 수 있어요. url이 있는 JSON 항목에는 http 같은 type도 있어야 해요.

   {
     "mcpServers": {
       "api-server": {
         "type": "http",
         "url": "${API_BASE_URL:-https://api.example.com}/mcp",
         "headers": {
           "Authorization": "Bearer ${API_KEY}"
         }
       }
     }
   }

우선순위, 커넥터, 그 밖의 세부 사항

• 같은 서버가 두 번 정의되면 Claude Code는 한 번만 연결하고, local, project, user, 플러그인, claude.ai 커넥터 순서로 처음 찾은 것을 써요. 항목은 병합되지 않고, 조직의 관리형 서버가 이 모두보다 우선해요.
• claude.ai 계정으로 Claude Code에 로그인하면 claude.ai에서 추가한 커넥터가 자동으로 나타나요.
• Claude Code 자체도 MCP 서버가 될 수 있어요. claude mcp serve로 Claude Desktop 같은 다른 클라이언트에 도구를 제공해요.
• 서버는 슬래시 명령으로 나타나는 프롬프트를 제공할 수도 있어요. Claude Code 슬래시 명령을 참고하세요.
• 원격 서버를 제거하면 Claude Code가 저장한 토큰은 삭제되지만 폐기되지는 않아요. 폐기하려면 먼저 claude mcp logout <name>을 실행하세요.

MCP와 토큰 사용량

도구 정의는 기본적으로 지연 로드돼요. Claude가 도구를 쓰기 전까지 컨텍스트에는 도구 이름과 서버 안내만 들어가므로, 서버를 많이 등록해도 예전보다 비용이 적어요. 그래도 서버마다 조금씩은 더해지니 쓰지 않는 서버는 /mcp에서 비활성화하고, gh, aws, gcloud처럼 CLI가 있으면 CLI를 우선 쓰세요. CLI는 도구 목록을 전혀 늘리지 않아요. 자세한 내용은 Claude Code 토큰 사용량 줄이는 방법을 참고하세요.

문제 해결: 서버가 연결되지 않을 때

• 인증이 필요하다고 표시될 때: /mcp를 열고 Re-authenticate를 고르거나 claude mcp login <name>을 실행하세요.
• "has a url but no type"이 나올 때: JSON 항목에 "type": "http"(또는 sse, ws)를 추가하세요. type이 없으면 Claude Code는 stdio로 취급해요.
• stdio 서버의 플래그가 사라졌을 때: 서버 명령 앞에 --를 넣어 Claude Code가 자기 플래그로 해석하지 않게 하세요.
• claude mcp list에 변수 누락 경고가 뜰 때: 그 변수를 설정하거나 :-default로 기본값을 주세요.
• 프로젝트 서버가 claude -p에서 로드되지 않을 때: 헤드리스에서는 승인 프롬프트가 없으니 설정을 확인하거나, --mcp-config와 --strict-mcp-config로 서버를 명시적으로 넘기세요.
• claude mcp로 추가하는 서버 이름에는 영문자, 숫자, 하이픈, 밑줄만 쓸 수 있어요.

AI 직원에게도 내가 쓰는 도구를 그대로

Claude Code가 이슈 트래커, 데이터베이스, 분석 도구에 닿는 통로가 MCP예요. Crewmark는 Claude Code, Codex, DeepSeek Harness, OpenCode 세션을 직무, 목표, 근무 시간을 가진 AI 직원으로 바꾸고, 하트비트로 깨워서 보드의 다음 이슈를 가져가게 해요. 프로젝트의 MCP 서버도 쓸 수 있는 상태로요.

1. .mcp.json 커밋하기

   project 스코프 서버는 내 세션과 똑같이 직원의 세션에서도 로드돼요. OAuth가 필요한 서버는 한 번만 대화형으로 로그인해 두세요.

2. 하트비트로 일을 시작하게 하기

   근무 시간 동안 직원은 15분, 30분, 60분마다 같은 대화에서 깨어나요. Claude Code를 능동적으로 만드는 방법을 참고하세요.

3. 직무마다 필요한 것만 주기

   SEO 직원에게는 Search Console을, 프로그래머에게는 GitHub와 Sentry를 주세요. AI 직원이란을 읽어 보세요.

Claude Code MCP 자주 묻는 질문