MCP 서버 연결 확인법: 목록 표시와 실제 도구 호출 구별

코딩 에이전트 CLI에서 MCP 서버가 목록에 보여도 그것만으로 도구가 작동한다고 판정할 수는 없다. macOS의 로컬 stdio 서버 하나를 기준으로 하면 설정 읽기, 서버 초기화, 실제 도구 호출은 서로 다른 출력으로 확인해야 한다. 실측과 공식 문서 확인은 모두 2026-11-03에 했다.

Codex에서는 없는 경로를 준 고장 설정도 enabled로 표시됐다. 성공 여부는 mcp_tool_call 이벤트의 도구 이름과 반환값으로 판정해야 했다.

MCP 서버가 목록에 있는데 왜 도구는 작동하지 않을까

MCP 공식 아키텍처·전송 문서에 따르면 로컬 stdio 연결에서 클라이언트는 서버를 자식 프로세스로 실행한다. 설정에 명령이 적혀 있는 것과 그 프로세스가 살아서 응답하는 것은 별개다.

그래서 이 글은 확인 과정을 등록·읽기, 시작·초기화, 실제 호출 세 단계로 나눈다. MCP 공식 명칭은 아니다. 실패 지점을 좁히려고 이 글에서 정한 진단 분류다.

MCP 서버 확인 세 단계 그림: 등록 단계에서는 정상 설정과 고장 설정이 모두 mcp list에 enabled로 보임, 시작 단계에서 고장 설정은 initialize 응답 전에 연결이 끊겼는데도 CLI 종료 코드 0, 호출 단계에서 mcp_tool_call read_text_file이 completed이고 반환 내용이 파일과 일치. 목록에 보인다고 도구를 쓴 것은 아니다.

설정 읽기가 통과해도 초기화나 도구 호출에서 멈출 수 있으므로 단계마다 다른 증거를 봐야 한다.

다른 폴더에서 서버가 보이지 않는 이유

Claude Code 공식 문서는 등록 범위를 local, project, user로 나눈다. 기본값 local은 현재 프로젝트에만 적용되며 ~/.claude.json의 프로젝트 경로별 항목에 저장된다.

Claude Code 2.1.274와 codex-cli 0.161.0으로 ~/workspace에서 직접 실행해 봤다. claude mcp list와 codex mcp list 모두 서버가 없다고 나왔다.

~/.claude.json에서 프로젝트 키와 서버 이름만 뽑아 보니 홈 폴더(~) 항목에는 chrome-devtools가 있었고 ~/workspace 항목에는 서버가 없었다. local 범위에 등록한 서버를 전역 설정으로 오해하면 다른 폴더에서 서버가 사라진 것처럼 보인다.

설정 등록과 실제 도구 호출은 어떤 출력으로 구별하는가

OpenAI Codex 공식 문서는 ~/.codex/config.toml의 [mcp_servers.<name>] 테이블로 서버를 구성한다고 설명한다. 이번에는 설정 파일을 쓰지 않으려고 실행별 -c 오버라이드만 썼다. 실험 전후 이 파일의 SHA-256 해시는 같았다.

실험 대상은 공식 저장소가 학습용 예제로 소개하는 참조 구현 @modelcontextprotocol/server-filesystem@2.1.0이다. 쓰기 도구도 있는 서버라서 <폴더>/data만 허용하고 읽기만 요청했다.

아래가 정상 설정의 목록 조회다. NPM_CONFIG_* 두 변수는 MCP 요구사항이 아니다. 이 컴퓨터의 npm 인증 오류(E401)를 피하려고 서버 프로세스에만 넘긴 값이다.

codex -c 'mcp_servers.demo.command="npx"' -c 'mcp_servers.demo.args=["-y","@modelcontextprotocol/server-filesystem@2.1.0","<폴더>/data"]' -c 'mcp_servers.demo.env.NPM_CONFIG_USERCONFIG="/dev/null"' -c 'mcp_servers.demo.env.NPM_CONFIG_REGISTRY="https://registry.npmjs.org"' -c 'mcp_servers.demo.startup_timeout_sec=30' mcp list

경로 인수만 없는 경로 <폴더>/does-not-exist로 바꿔 mcp list와 mcp get demo --json을 다시 실행했다. 정상 설정과 고장 설정 모두 list의 Status는 enabled, get의 JSON은 "enabled": true였다. 이 표시는 설정을 읽었다는 뜻일 뿐, 서버가 기동했다는 증거는 되지 못한다.

Claude Code 문서에 따르면 claude mcp list와 claude mcp get은 Connected 같은 연결 상태도 보여 준다. 이 상태를 Codex의 enabled와 같은 신호로 보면 안 된다.

고장 설정으로 에이전트를 실행하자 실패가 드러났다.

codex (같은 -c 옵션, 경로만 <폴더>/does-not-exist) exec --json --skip-git-repo-check -s read-only 'Use only the demo MCP server to read <폴더>/data/proof.txt. … If demo is unavailable report that fact and stop.'

JSON 이벤트에는 mcp_tool_call, tool: list_mcp_resources, status: failed와 함께 다음 오류가 남았다.

resources/list failed: failed to get client: MCP startup failed: handshaking with MCP server failed: connection closed: initialize response: connection closed: initialize response

read_text_file이 실행된 흔적은 없다. 에이전트는 서버를 쓸 수 없다고 보고한 뒤 턴을 끝냈고, 그래서 CLI 종료 코드는 0이었다.

정상 경로에서는 도구 이름까지 지정해 실행했다.

codex (같은 -c 옵션) exec --json --skip-git-repo-check -s read-only 'Call the demo MCP server read_text_file tool on <폴더>/data/proof.txt. … return its full exact content without commentary.'

이번에는 mcp_tool_call에 tool: "read_text_file", status: "completed", error: null이 찍혔다. 반환 본문에는 테스트 파일 두 줄이 끝 줄바꿈까지 그대로 있었다. 모델의 마지막 답변에서는 그 줄바꿈이 빠졌다. 그러니 판정은 도구 응답 이벤트로 해야 한다.

확인 단계판정 근거실패 시 현상
등록·읽기mcp list의 enabled이름이 없거나 다른 폴더에서만 보임
시작·초기화initialize 응답, tools/list 도구 14개MCP startup failed
실제 호출mcp_tool_call의 tool, status, 반환 본문종료 코드 0인데 사용 불가 보고, isError: true

초기화와 도구 호출은 왜 실패하는가

원인을 보려고 고장 설정의 서버 명령을 셸에서 직접 실행했다.

env NPM_CONFIG_USERCONFIG=/dev/null NPM_CONFIG_REGISTRY=https://registry.npmjs.org npx -y @modelcontextprotocol/server-filesystem@2.1.0 <폴더>/does-not-exist
Error: None of the specified directories are accessible

stderr에 이 오류가 나오고 종료 코드 1로 끝났다. 서버가 허용 경로 검사에서 바로 종료하는 바람에 initialize에 응답하지 못한 것으로 본다. 시작 제한 시간 startup_timeout_sec을 늘려도 풀리지 않는 실패다.

원시 stdio 테스트는 protocolVersion: "2025-06-18"을 썼다. initialize, tools/list(도구 14개), 허용 경로 안의 파일 읽기가 모두 성공했다. 2026-07-28 규격에는 초기 핸드셰이크가 없는 방식과 server/discover가 있다. 따라서 이 순서를 모든 MCP 연결로 일반화하지 않는다.

허용 경로 밖 파일을 tools/call로 요청하자 연결은 유지된 채 isError: true와 Access denied - path outside allowed directories 문구가 돌아왔다. 접근 거부는 시작 실패가 아니다. 연결이 성립한 뒤 서버가 정상적으로 처리한 결과다.

설정 파일을 직접 고치지 않고 확인하는 절차

  1. <폴더>/data/proof.txt에 고유 문자열 두 줄을 저장한다. 이 내용은 프롬프트에 알려 주지 않는다.
  2. 작업 폴더에서 claude mcp list 또는 codex mcp list로 기존 등록 상태와 범위를 확인한다.
  3. Codex에서 -c 옵션으로 서버 버전과 허용 경로를 지정하고 mcp get demo --json으로 설정이 읽히는지 본다.
  4. 셸과 기본 파일 도구를 쓰지 말고 read_text_file만 호출하라고 지시해 exec --json을 실행한다.
  5. mcp_tool_call의 tool, status, error와 반환 본문을 원본 파일과 대조한다. 초기화에서 막히면 서버 명령을 셸에서 직접 실행해 stderr를 본다.

이번 검증의 한계

Claude Code의 --mcp-config, --strict-mcp-config를 쓴 호출 세션과 /mcp 화면은 문서로만 확인했고 직접 실행하지 않았다. 원격 HTTP/SSE 서버, OAuth, Windows 인용부호, 느린 네트워크에서의 시간 초과도 측정하지 않았다.

MCP의 기본 개념은 MCP란 무엇인가에서 다뤘다. 다른 폴더에서 서버가 빠졌던 경험은 MCP vs CLI에 정리했다.

결론

MCP 서버가 목록에 보이거나 CLI 종료 코드가 0이어도 도구가 작동했다고 볼 수 없다. 기준은 설정 읽기, 초기화, 실제 호출 중 어디까지 증거가 남았는지다. 최종 성공은 mcp_tool_call 이벤트의 도구 이름과 반환값으로 판정한다. 지금 쓰는 서버가 의심스럽다면 작은 텍스트 파일 하나로 JSON 호출 로그에 도구 이름과 파일 내용이 찍히는지부터 확인해 보자.

댓글

댓글 쓰기

이 블로그의 인기 게시물

AI 코딩 스킬, 많을수록 좋을까 — 자산이 부채로 바뀌는 손익분기

이미지
AI 코딩 스킬은 자산이다. 처음 몇 개는 그렇다. 그런데 수가 늘면 세금이 붙는다. 어느 스킬이 뜰지 예측이 안 되고, 도구 출력이 컨텍스트를 먹고, 모델이 바뀌면 쌓은 걸 전부 다시 만진다. 스킬을 관리하는 앱이 시장에 나온 게 그 신호다. 만들지 말라는 게 아니다. 만든 만큼 쳐내야 자산으로 남는다. 스킬은 자산으로 시작한다, 그런데 요즘 개발자들이 자기 .claude 디렉터리를 통째로 공개한다. TypeScript 교육자 Matt Pocock도 스킬 묶음을 GitHub에 올렸다. 제목이 “Skills for Real Engineers”이고, 소개가 “내 .claude 디렉터리에서 바로”다. skills.sh 같은 스킬 레지스트리도 생겼다. 스킬이 자산인 건 맞다. 손으로 반복하던 작업을 트리거 한 줄로 줄인다. 결과도 매번 일정해진다. 그래서 다들 쌓는다. 그런데 같은 GitHub에 묘한 게 같이 뜬다. 스킬을 “관리하고 동기화하고 정리”하는 데스크톱 앱이다. skills-manager는 Cursor·Claude Code·Codex 등 15개 넘는 도구의 스킬을 한곳에서 관리한다고 소개한다. 자산을 관리하는 전용 앱이 필요해졌다는 건, 그 자산이 관리 대상이 됐다는 뜻이다. 관리 대상은 곧 부담이다. 여기서 질문이 갈린다. AI 코딩 스킬은 많을수록 좋은가. 다음 중 하나라도 있나 비슷한 일을 하는 스킬이 둘 이상이라, 어느 게 뜰지 헷갈린 적이 있다. 스킬 하나를 고쳤더니 엉뚱한 데서 다른 게 어긋난 적이 있다. 내가 무슨 스킬을 만들어뒀는지, 목록을 열어봐야 기억나는 적이 있다. 셋 중 하나라도 해당되면 이미 부채 구간에 발을 걸친 것이다. 세 신호를 하나씩 본다. 신호 1 — 어느 스킬이 뜰지 예측이 안 된다 스킬이 늘면 비슷한 트리거를 여럿이 주장한다. “리뷰”라는 말에 코드 리뷰 스킬도 반응하고, 글 리뷰 스킬도 반응한다. 그러면 매 요청마다 “어느 스킬을 부를지” 판별하는 비용이 붙는다. 자동 라우팅 점...
자세한 내용 보기

M4 Max 128GB 로컬 LLM 4종 속도 비교 — 실측 기록과 한계

이미지
M4 Max 128GB에서 로컬 LLM은 얼마나 빠를까? 이 글의 과거 표에서는 gemma4:latest가 88 tok/s로 가장 높고, gemma4:26b는 85 tok/s다. gpt-oss:120b 47 tok/s, qwen3.6:35b-a3b 25 tok/s가 뒤를 잇는다. 처리량 표이지 정답률이나 코딩 품질 순위가 아니다. 작성자: 닥터조지. 2026년 4월 게시 당시 측정 기록 / 편집 보완: 2026-09-23. 기존 수치는 그대로 보존했고 이번에 모델을 다시 실행하지 않았다. 초판 제목의 llama3.3 표기와 “26B가 가장 빠르다”는 도입은 표와 일치하지 않아 바로잡았다. 원문의 장비·런타임·모델 표기는 당시 기록이다. 표의 qwen3.6:35b-a3b 는 원문에서 사용한 축약 표기이며, Q8과 qwen3.6:35b-a3b-q8_0 표기는 당시 본문 기록에서 가져왔다. 모델 파일이나 digest를 이번에 확인한 것은 아니다. 원 프롬프트 전문, 모델 digest, 반복 횟수와 개별 원시 응답이 이 글에 없어 표의 숫자를 그대로 재현했다고 확인할 수는 없다. 특히 latest 는 고정 버전 식별자가 아니다. 아래는 M4 Max 128GB 한 대에서 기록한 네 모델의 처리량이다. 모델 구조, 양자화, 크기가 동시에 다르므로 어느 한 요인만의 효과를 분리한 실험으로 읽으면 안 된다. 모델 크기만으로 속도를 예측하기 어려운 이유 원문은 gpt-oss:120b 를 총 117B, 활성 약 5.1B의 MoE로 기록했다. 활성 파라미터 수만으로 실제 생성 속도를 계산할 수는 없다. 모델 구조에 따른 메모리 접근 차이는 가능한 설명이지만, 이 표는 메모리 대역폭이나 접근 패턴을 직접 계측한 자료가 아니다. 생성 속도 차이만으로 병목의 원인을 확정하지 않는다. 당시 표의 gemma4:26b 는 gpt-oss:120b 보다 높은 생성 처리량을 보였다. 다만 이 결과를 모든 Dense 모델과 MoE 모델의 우열로 일반화할 수는 없다. 같은 ...
자세한 내용 보기

Opus 5는 더 잘 쓰고, 더 AI답게 쓴다 — 세 모델 첫날 실측

이미지
Claude Opus 5가 나온 다음 날, 세 모델에게 같은 시험지를 줬다. 결과부터 적는다. 글 품질 점수는 신형일수록 올랐다. 그런데 문장 리듬은 신형일수록 고르게, 그러니까 더 AI답게 변했다. 여기서 “AI답게”는 말투가 기계 같다는 뜻이 아니다. 문장 길이와 어미가 균질해진다는 뜻이고, 그 균질함이 통계 탐지기가 AI 글을 잡아낼 때 쓰는 바로 그 지문이다. 발표는 두 가지를 팔았다 새 모델이 나오면 벤치마크 표부터 보게 된다. 그 표는 전부 만든 쪽이 자기 시험지로 채점한 결과다. 내 작업에서 뭐가 달라지는지는 표에 없다. 그래서 표를 덮고 시험지를 직접 만들었다. 7월 24일 발표에서 Anthropic은 크게 두 가지를 내세웠다. 하나, 자기 작업을 검증하며 성공할 때까지 반복하는 능력이 강해졌다. 둘, 응답이 더 명확하고 간결해졌다. 벤치 수치는 여기 옮기지 않는다. 이 글이 확인할 건 저 두 문장이 내 작업물에서 어떻게 나타나느냐다. 같은 시험지 두 장 시험지는 두 장이다. 첫째는 글쓰기다. 주제·허용 사실·문체 규칙을 고정한 한국어 블로그 초안 스펙을 만들어 세 모델에 원샷으로 줬다. 둘째는 코딩 진단이다. 내 수집기에서 한 달 넘게 죽어 있던 실제 버그(reddit 수집 429 연쇄 실패)를 읽기 전용으로 진단하게 했다. 모든 주장에 파일과 행 번호 인용을 의무로 걸었다. 대상은 Opus 4.8, Fable 5, Opus 5. 각 모델의 정체는 시스템 프롬프트 자기보고로 확인했다. 채점은 사람 감이 아니다. 글은 발행 글 29편에서 뽑은 결정론 밴드(파이썬 스크립트)와 10점 감점제 루브릭으로, 진단은 미리 고정해 둔 정답표와 인용 실물 대조로 매겼다. 실측 1 — 더 잘 쓸수록 더 고르다 숫자부터 본다. 지표 Opus 4.8 Fable 5 Opus 5 발행 글 기준 문장 길이 변주(변동계수) 0.316 0.220 0.274 0.417 이상 행 길이 변주 0.266 0.23...
자세한 내용 보기