MCP 서버 만들기, 코드보다 먼저 볼 것
직접 하나를 만들어 클로드 코드에 붙여 보려는 단계라면 이 글이 맞습니다. 이미 다른 MCP 서버를 써 봤지만, 내 API나 로컬 프로그램에 맞춘 도구가 필요해진 경우도 여기에 해당합니다.
한 번 만든다고 바로 끝나지는 않습니다. 서버 구현, 실행 방식, 클로드 코드 등록, 도구 목록 확인은 각각 따로 확인해야 하며, 앞 단계가 멀쩡해 보여도 다음 단계에서 멈출 수 있으므로 처음부터 작업 순서를 나눠 잡는 편이 좋습니다.
먼저 확인한 사실이 있습니다. 클로드 코드 공식 문서에는 MCP 서버를 만드는 코드 예제가 없습니다. 문서는 구현을 다른 곳으로 넘기며, 처음 시도할 때 놓치기 쉬운 지점도 남아 있습니다.
먼저 결론부터
- 클로드 코드 공식 문서에는 MCP 서버 구현 코드 예제가 없고, MCP 공식 사이트와
mcp-server-dev플러그인을 안내합니다. - 처음 만든다면 MCP 공식 사이트의 TypeScript·Python SDK 문서나 플러그인 대화로 뼈대를 만드는 편이 빠릅니다.
- 로컬 HTTP 서버는 아래 명령으로 등록하며, 서버의 MCP 엔드포인트 주소를 정확히 넣어야 합니다.
claude mcp add --transport http myserver http://localhost:3000/mcp- npm 패키지로 실행하는 서버는 stdio 방식으로 등록하고,
npx뒤의 실행 명령까지 함께 전달합니다.
claude mcp add --transport stdio myserver -- npx -y @myorg/mcp-server- 팀이 함께 쓸 서버는
--scope project를 붙여.mcp.json에 저장한 뒤 커밋합니다. - 연결 뒤 도구가 보이지 않으면 등록 상태, 서버 프로세스, 도구 목록 반환을 순서대로 나눠 확인해야 합니다.
공식 문서에서 시작점을 고릅니다
출발점부터 다릅니다.
공식 문서를 직접 확인해 보니 클로드 코드 문서는 서버를 만드는 소스 코드나 최소 구현을 싣지 않았고, 구현 방법은 MCP 공식 사이트의 서버 만들기 문서로 넘기며, 대화형 제작이 필요할 때는 mcp-server-dev 플러그인을 설치해 쓰도록 안내합니다.
먼저 길을 고르세요.
MCP 공식 사이트 문서는 TypeScript와 Python을 지원합니다. 기존 서비스의 언어와 배포 환경이 정해졌다면 해당 SDK 예제에서 시작하면 됩니다. 구현 방향이 아직 흐리다면 플러그인이 더 편합니다.
/mcp-server-dev:build-mcp-server이 명령은 플러그인을 설치한 뒤 클로드 코드 안에서 실행합니다. 대화하면서 서버를 만들 수 있으므로, 처음부터 도구 정의와 실행 구조를 모두 설계할 필요가 없습니다(단, 실제 API 권한과 실행 환경은 직접 준비해야 합니다).
서버 구현의 출발점
서버는 도구를 노출하고 요청을 처리한 뒤 결과를 돌려주는 형태를 갖춰야 합니다. 어떤 도구를 만들지부터 작게 정하는 편이 좋습니다. 예를 들어 내부 API 하나를 조회하거나, 로컬 앱의 기능 하나를 실행하는 식입니다.
처음부터 여러 도구를 넣으면 원인을 가리기 어렵습니다. SDK 예제나 플러그인으로 서버를 띄운 다음, 도구 하나가 정상 응답하는지 확인하고 범위를 넓히세요. 서버 구현과 클로드 코드 등록을 한 번에 바꾸면 어느 쪽에서 문제가 생겼는지 판단하기 어려워집니다.
실행 방식도 초기에 정해야 합니다. HTTP 서버는 주소로 접속하고, stdio 서버는 클로드 코드가 지정한 명령을 실행해 표준 입출력으로 통신합니다. 배포 형태가 npm 패키지라면 stdio 등록 흐름이 자연스럽습니다.
Claude Code에 등록하는 방법
로컬에서 3000 포트로 실행 중인 HTTP 서버는 다음처럼 붙입니다.
claude mcp add --transport http myserver http://localhost:3000/mcpnpm으로 배포한 stdio 서버는 다음 명령을 씁니다.
claude mcp add --transport stdio myserver -- npx -y @myorg/mcp-serverHTTP와 stdio는 등록 명령의 모양만 다른 것이 아니라, 문제가 났을 때 확인할 대상도 달라집니다. HTTP는 서버 주소와 엔드포인트 응답을 먼저 보고, stdio는 클로드 코드가 실행할 명령이 터미널에서 실제로 프로세스를 띄우는지 확인해야 합니다.
팀 설정은 프로젝트에 둡니다.
claude mcp add --scope project --transport http myserver http://localhost:3000/mcp이 경우 설정은 .mcp.json에 들어가므로 파일을 커밋하면 됩니다. 서버 주소에 개인 환경 값이 들어간다면 팀이 그대로 실행할 수 있는지도 함께 점검해야 합니다.
도구 목록이 안 보일 때
먼저 등록 상태를 봅니다.
claude mcp list
claude mcp get <이름>HTTP 서버라면 서버가 살아 있는지부터 확인합니다.
curl -I <url>stdio 서버라면 등록에 넣은 실행 명령을 터미널에서 직접 실행해 프로세스가 뜨는지 봅니다. 시작 시간이 길다면 아래처럼 클로드 코드의 대기 시간을 늘릴 수 있습니다.
MCP_TIMEOUT=60000 claude세션 안에서는 /mcp를 열어 해당 서버가 실제로 어떤 도구를 내놓는지 확인합니다. 이 맥에 붙어 있는 서버 열두 개 가운데 로컬 데스크톱 앱에 연결한 하나를 확인했을 때, 연결은 되었지만 도구 목록을 받아 오지 못했고 상태 줄에는 요청 시간 초과가 표시됐습니다.
이 경우 볼 곳은 도구 목록입니다.
서버 연결이 성립했다면 등록 명령보다 도구 목록을 반환하는 서버 쪽을 살펴야 합니다. /mcp에서 목록이 비어 있거나 시간 초과가 난다면, 도구 등록 과정과 목록 응답이 멈추는 지점을 확인하는 순서가 맞습니다(로컬 앱 연동 서버에서 특히 구분이 필요합니다).
마무리
다음 작업은 작동하는 도구 하나를 정하고, MCP 공식 사이트의 SDK 예제 또는 플러그인으로 서버를 띄우는 일입니다. 그 뒤 등록 명령을 실행하고 /mcp에서 도구 이름이 보이는지 확인하세요. 이 순서면 구현 문제와 연결 문제를 섞지 않고 처리할 수 있습니다.
클로드 코드 공식 문서에 제작 코드가 없는 점은 빠진 설명처럼 보일 수 있습니다. 다만 실제 문서가 서버 구현을 MCP 공식 사이트와 mcp-server-dev 플러그인으로 넘기기 때문에, 코드 작성법은 그 경로에서 찾고 클로드 코드 문서에서는 등록과 점검에 집중하는 편이 맞습니다.