MCP 서버 연결 안 될 때, Claude Code에서 먼저 보는 5가지

byVibe on • • 2 min read
0

MCP 서버 연결 안 될 때, Claude Code에서 먼저 보는 5가지

MCP 서버 연결 안 될 때, Claude Code에서 먼저 보는 5가지

MCP 서버 연결 안 될 때 제일 먼저 볼 것

MCP 서버 연결 안 될 때 Claude Code에서 제일 답답한 건 에러가 화려하지 않다는 점입니다. 그냥 failed로 뜨거나, 서버는 보이는데 도구를 안 쓰거나, 터미널에서는 되는데 Claude Code 안에서는 조용히 실패하죠.

제가 크게 보는 지점은 기능보다 연결 순서입니다. MCP는 Slack, GitHub, DB, 파일 같은 외부 도구를 Claude Code에 붙이는 방식인데, 한 군데만 틀려도 전체가 안 움직이거든요. 매달 코딩 AI 구독료를 내는 입장에선 이런 연결 문제로 30분씩 날리는 게 제일 아깝습니다.

아래 순서대로 보면 대부분은 잡힙니다. 거창한 디버깅보다 먼저 봐야 할 건 5개입니다.

failed 상태가 보이면 서버가 실제로 켜지는지 확인

Claude Code나 Agent SDK 쪽에서 MCP 서버 상태가 failed로 나오면 서버 프로세스 자체가 시작을 못 했을 가능성이 큽니다. 패키지가 없거나, Node.js 경로가 안 잡혔거나, 원격 서버 URL이 막힌 경우가 많아요.

먼저 Claude Code 밖에서 같은 명령을 직접 실행해봅니다.

npx -y @modelcontextprotocol/server-filesystem C:\Users\Chul\Desktop
✓이렇게 나오면 OK: 터미널이 바로 죽지 않고 서버가 대기하거나, 별도 에러 없이 실행 상태로 남아 있으면 출발선은 통과입니다.
⚠여기서 막히면 이것 확인: npx가 안 먹으면 Node.js 설치와 PATH를 먼저 보세요. Windows에서는 새 터미널을 열어야 PATH가 반영되는 경우도 있구요.

환경변수 빠지면 로그인 문제처럼 보임

MCP 서버 연결 안 될 때 인증 토큰 문제는 생각보다 자주 나옵니다. GitHub, Notion, Supabase 같은 서버는 토큰이 없으면 서버는 뜨는 척해도 실제 도구 호출에서 막힐 수 있습니다.

.mcp.json에서 env를 직접 넘기는 게 제일 덜 헷갈립니다.

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } } } }
✓이렇게 나오면 OK: Claude Code 안에서 서버 상태가 connected로 바뀌고, GitHub 도구 목록이 보이면 됩니다.
⚠여기서 막히면 이것 확인: PowerShell에서 토큰이 실제로 잡혔는지 먼저 봅니다.
$env:GITHUB_TOKEN

빈 줄이면 Claude Code 문제가 아니라 내 터미널 환경 문제입니다. 이 단계에서 시간을 많이 씁니다. 진짜로.

서버는 연결됐는데 도구를 안 쓰는 경우

서버 상태가 connected인데 Claude Code가 MCP 도구를 안 쓰면 연결 문제가 아닐 수 있습니다. 도구 사용 권한이 빠진 상태일 때 이런 식으로 보입니다.

Agent SDK에서는 allowedTools를 명시해야 합니다. 서버 이름이 github라면 도구 이름은 보통 mcp__github__list_issues 같은 형태로 붙습니다.

allowedTools: ["mcp__github__*"]
✓이렇게 나오면 OK: Claude가 GitHub 서버의 도구를 실제로 호출하기 시작합니다. 와일드카드는 그 서버의 도구를 한 번에 허용할 때 편합니다.
⚠여기서 막히면 이것 확인: 서버 이름을 대충 적으면 안 됩니다. mcp__servername__toolname 구조라서 .mcp.json에 적은 이름과 allowedTools의 이름이 맞아야 하거든요.

timeout은 느린 서버부터 의심

MCP 서버 연결 안 될 때 60초 근처에서 실패한다면 서버 시작이 느린 쪽을 봐야 합니다. 특히 Python 가상환경을 켜거나, 큰 패키지를 처음 설치하거나, 원격 API 인증까지 같이 하는 서버는 시작 시간이 길어질 수 있어요.

이럴 땐 Claude Code부터 다시 만지지 말고 서버 명령만 따로 실행합니다.

npx -y @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem C:\Users\Chul\Desktop
✓이렇게 나오면 OK: MCP Inspector에서 tools, resources, prompts가 보이면 서버 자체는 살아 있습니다.
⚠여기서 막히면 이것 확인: 처음 실행이라 패키지를 받는 중인지, 회사 네트워크가 npm 다운로드를 막는지, 백신이 로컬 프로세스 실행을 잡는지 봐야 합니다. 원격 HTTP 서버라면 브라우저나 curl로 URL이 열리는지도 같이 보세요.

stdout에 로그 찍으면 프로토콜이 깨짐

직접 만든 MCP 서버에서 제일 묘한 오류가 이겁니다. stdio 방식 서버는 stdout으로 MCP 메시지를 주고받습니다. 여기에 console.log 같은 일반 로그가 섞이면 Claude Code 입장에서는 정상 JSON 메시지가 아닌 걸 받은 셈이 됩니다.

Node 서버라면 일반 로그는 stderr로 빼는 쪽이 안전합니다.

console.error("server started")

Python도 마찬가지입니다.

import sys
print("server started", file=sys.stderr)
✓이렇게 나오면 OK: stdout에는 MCP 응답만 남고, 로그는 stderr로 빠집니다.
⚠여기서 막히면 이것 확인: 서버 파일 안에 print, console.log, 디버그 배너가 숨어 있는지 검색해보세요. 멋진 시작 문구 하나 때문에 연결이 깨지는 경우가 있습니다.

MCP 서버 연결 안 될 때 제 순서

제 기준에선 순서가 있습니다. 서버 명령 직접 실행, env 확인, .mcp.json 문법 확인, allowedTools 확인, Inspector 실행. 이 5개를 먼저 보면 Claude Code를 지웠다 까는 일까지는 잘 안 갑니다.

특히 Windows에서는 PATH와 환경변수가 자주 걸립니다. macOS나 Linux 글을 보고 그대로 따라 하면 명령은 맞는데 경로가 안 맞는 일이 생기죠. 회사 노트북에서는 보안 프로그램이 npx 실행을 늦추는 경우도 있구요.

MCP 서버 연결 안 될 때 제일 좋은 신호는 문제가 작게 쪼개지는 겁니다. 서버가 안 켜지는지, 켜졌는데 권한이 없는지, 권한은 있는데 Claude가 안 쓰는지. 여기까지만 나뉘면 절반은 이미 고친 셈입니다.

FAQ

.mcp.json은 어디에 둬야 하나요?

프로젝트에서 쓰는 설정이면 프로젝트 루트에 두는 방식이 제일 관리하기 편합니다. 여러 프로젝트에서 전부 쓸 서버라면 사용자 설정으로 빼도 되지만, 처음엔 프로젝트 안에서 눈에 보이게 두는 편이 덜 헷갈립니다.

SSE와 HTTP는 뭐가 다른가요?

로컬에서 npx로 켜는 서버는 보통 stdio입니다. URL을 넣는 원격 서버는 HTTP 또는 SSE를 씁니다. 요즘은 Streamable HTTP 쪽이 더 자주 보이고, 예전 SSE 서버는 호환용으로 남아 있는 경우가 있습니다.

Claude Code가 서버는 보는데 도구를 안 쓰면 뭘 보나요?

⚠allowedTools를 먼저 봅니다. 서버 연결과 도구 사용 허용은 같은 일이 아닙니다. 연결만 됐다고 바로 도구를 마음대로 쓰는 구조가 아니라서 이 단계에서 막히는 사람이 많습니다.

MCP는 잘 붙으면 매일 쓰는 기능이 되는데, 처음 연결할 때는 작은 철자 하나가 하루 기분을 망칩니다.

Related Searches

  • 🔍 Claude Code 사용법
  • 🔍 Claude Code 비교
  • 🔍 MCP 서버 연결 사용법
  • 🔍 MCP 서버 연결 비교
  • 🔍 MCP 오류 사용법
  • 🔍 MCP 오류 비교
4.94 / 169 rates

댓글 쓰기

다음 이전