[MCP] 3. 연결 : Claude에 MCP 연결하는 법

(MCP 시리즈 ③) 연결

서버 혼자 떠 있어 봐야 소용없다. 클라이언트가 붙어야 도구가 산다. 제일 흔한 건 Claude Desktop에 붙이는 건데, 설정 파일 한 곳만 고치면 된다. claude_desktop_config.json을 열어 이렇게 서버를 등록한다.

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

경로는 반드시 절대 경로로 넣는다. 상대 경로로 넣으면 앱이 어디서 실행하느냐에 따라 못 찾는다. 이거 때문에 “왜 안 뜨지” 하고 한참 헤매는 사람이 많다. 저장하고 Claude Desktop을 완전히 껐다 켜면, 입력창 근처에 도구 아이콘이 생긴다.

이제 “서울 날씨 알려줘”라고 물으면 흐름이 이렇게 돈다. 모델이 질문을 보고 get_forecast 도구가 필요하다고 판단 → 서버에 호출을 보냄 → 서버가 결과를 돌려줌 → 모델이 그 결과를 근거로 답변. 이 왕복이 사용자 눈에는 그냥 “날씨를 아는 챗봇”으로 보인다.

붙였는데 서버가 자꾸 죽거나 연결이 끊긴다면, 제일 흔한 범인은 표준출력 오염이다. stdio 전송은 표준출력(stdout)으로 JSON-RPC 메시지를 주고받는데, 여기에 print() 한 줄이라도 끼면 그게 프로토콜에 섞여 깨진다. 로그를 찍고 싶으면 반드시 표준에러(stderr)로 보내야 한다. 이거 하나로 “왜 인스펙터에선 되는데 Claude에선 죽지”의 절반은 설명된다.

import sys

# stdio 서버에서 디버그는 stdout이 아니라 stderr로
print("여기까지 왔다", file=sys.stderr)   # OK
# print("여기까지 왔다")                  # 프로토콜 깨짐

붙였는데 안 뜰 때 — 점검 순서

MCP 서버가 목록에 안 나타나는 건 대부분 몇 가지 뻔한 이유다. 위에서부터 짚어 내려가면 열에 아홉은 잡힌다.

• 경로가 절대 경로가 맞나(상대 경로면 앱 실행 위치에 따라 못 찾는다).
• command가 시스템에서 실제로 실행되나 — python 대신 which python의 전체 경로나 uv가 필요할 수 있다.
• 설정 JSON 문법이 깨지지 않았나(콤마·따옴표 하나로 전체가 무효가 된다).
• 서버를 터미널에서 단독 실행했을 때 정상으로 뜨나(앱 문제인지 서버 문제인지 분리).
• 설정을 고친 뒤 앱을 완전히 종료했다 재시작했나.

비밀 값은 env로 넘긴다

API 키 같은 민감한 값은 args에 박지 말고 env 블록으로 넘긴다. 그러면 서버 프로세스에 환경변수로 주입돼, 키가 명령줄이나 대화·로그에 남지 않는다.

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": { "API_KEY": "여기에-키" }
    }
  }
}

stdio vs 원격(HTTP)

위 방식은 로컬에서 프로세스를 띄우는 stdio 방식이다. 서버가 다른 머신이나 클라우드에 있으면 HTTP 기반 원격 연결로 붙인다. 둘의 쓰임이 다르다.

	stdio(로컬)	원격(HTTP)
서버 위치	내 PC	다른 머신·클라우드
등록 정보	실행 명령·경로	URL·인증 토큰
적합	개인 로컬 도구	팀이 공유하는 서비스

Claude Code·Cursor라면 — 실제 등록 명령

Claude Desktop만이 아니다. 터미널의 Claude Code는 명령 한 줄로 붙는다 — JSON을 직접 만질 일이 없다.

# 로컬(stdio) 서버 등록
claude mcp add weather -- python /absolute/path/to/server.py

# 원격(HTTP) 서버 등록 — 인증 헤더까지
claude mcp add ordersvc --transport http https://mcp.example.com/mcp \
    --header "Authorization: Bearer YOUR_TOKEN"

claude mcp list        # 등록 확인
claude mcp remove weather

Cursor는 설정 파일(.cursor/mcp.json — 프로젝트별, 또는 전역 ~/.cursor/mcp.json)에 Claude Desktop과 같은 모양의 JSON을 넣는다. 등록 위치만 다르니 표로 접어두자.

클라이언트	등록 위치
Claude Desktop	claude_desktop_config.json
Claude Code	claude mcp add 명령 (프로젝트/전역 스코프)
Cursor	.cursor/mcp.json (프로젝트) / ~/.cursor/mcp.json (전역)

자주 묻는 질문 (FAQ)

Claude에 MCP를 어떻게 붙이나요?

Claude Desktop이나 Claude Code의 설정에 MCP 서버 실행 명령·인자를 등록하면 됩니다. 등록하면 해당 서버의 도구가 자동으로 목록에 나타납니다.

여러 MCP 서버를 동시에 붙일 수 있나요?

가능합니다. 각 서버가 도구 세트를 제공하고, 클라이언트가 이를 합쳐서 함께 사용합니다.