"MCP 서버 코드를 만들었는데 호스트에서 도구가 보이지 않으면, 서버를 더 고치기 전에 연결 단계부터 나눠 보는 게 좋아요. TypeScript SDK의 서버 패키지와 클라이언트 패키지를 구분하고, 연결 뒤 도구 목록을 요청하면 어디까지 통신했는지 확인할 수 있어요. 2026년 10월 5일 공개된 2.3.1 릴리스와 그 버전의 공식 문서를 기준으로 로컬 stdio 연결을 짚어 볼게요.
설치한 패키지 이름부터 맞춰요
검색해서 찾은 코드가 모두 같은 세대의 SDK를 쓰는 건 아니에요. 공식 README는 v2의 서버와 클라이언트를 별도 패키지로 안내해요. 예전 @modelcontextprotocol/sdk 예제의 import 경로를 새 패키지 코드 사이에 그대로 끼워 넣으면, 연결을 시도하기도 전에 막힐 수 있어요.
서버 쪽 시작점은 @modelcontextprotocol/server예요. 연결을 점검할 작은 클라이언트에는 @modelcontextprotocol/client를 써요. 설치 명령을 적어 두려면 bun add @modelcontextprotocol/server@2.3.1처럼 버전까지 남겨 주세요. 도구의 입력 스키마에 Zod를 쓰는 예제라면 그 의존성도 따로 필요해요.
여기서 2.3.1의 변경을 과장해서 읽지는 말아요. 릴리스에는 server-legacy 인증 도우미의 expectedResource 옵션과 패키지 소개 페이지 수정이 적혀 있어요. 서버·클라이언트 패키지 분리는 v2의 구조예요. stdio가 이번 패치에서 새로 생겼다는 뜻은 아니에요.
터미널에서 켠 서버와 호스트가 켠 서버를 구분해요
stdio는 클라이언트가 서버 프로세스의 표준 입력과 표준 출력을 통해 대화하는 방식이에요. 공식 첫 클라이언트 예제에서는 StdioClientTransport에 실행 명령과 인자를 넣고, client.connect(transport)를 호출해요. 이때 클라이언트가 자식 프로세스를 띄우고 초기 연결을 진행해요.
예를 들어 서버의 진입 파일을 src/index.ts로 정했다면, 호스트 설정에 적힌 실행 명령이 실제로 그 파일을 가리키는지 보세요. 다른 폴더에서 호스트가 시작될 수 있으니 상대 경로가 무엇을 기준으로 해석되는지도 확인해야 해요. 터미널에서 실행된다는 사실만으로 호스트 설정까지 맞았다고 볼 수는 없어요.
진단용 메모에는 실행 파일 위치와 작업 폴더를 함께 적어 두면 편해요. 같은 프로젝트 이름을 쓴 폴더가 두 곳이라면 더 필요하고요. 코드를 고친 폴더와 호스트가 실행한 폴더가 다른 상황은 패키지를 다시 설치해도 해결되지 않아요.
연결 다음에는 도구 이름이 나오는지 봐요
서버가 켜졌다는 메시지를 보는 것과 MCP 도구를 확인하는 것은 단계가 달라요. 공식 클라이언트 문서는 연결 후 listTools()로 등록된 도구 목록을 받고, 그 뒤 callTool()로 이름과 arguments를 보내도록 안내해요. 먼저 목록에 기대한 도구가 있는지 확인해 보세요.
가령 메모를 조회하는 read_note 도구를 만들었다고 해 볼게요. 이름은 목록에 나오는데 호출만 실패한다면, 다음 확인 대상은 입력값이에요. id를 받기로 했는데 noteId를 보냈는지, 숫자만 받는 입력에 문자열을 넣었는지처럼 요청과 스키마를 나란히 놓고 볼 수 있어요. 실제 서비스 데이터를 쓰기 전에는 작은 예시 입력으로 범위를 좁히는 편이 편해요.
호스트 화면에서 실패 안내를 받았을 때도 같은 순서로 메모하면 좋아요. 연결 자체가 끝나지 않았는지, 도구 목록은 받았는지, 특정 도구 호출에서 문제가 났는지를 한 줄씩 남겨요. “MCP가 안 된다”는 기록보다 다음에 살펴볼 지점이 뚜렷해져요.
로그를 찍는 위치와 종료 처리가 남아요
stdio 서버의 stdout은 프로토콜 메시지가 오가는 통로예요. 공식 서버 튜토리얼도 진단 메시지는 console.error로 stderr에 보내라고 안내해요. 도구 처리를 추가하다가 console.log로 상태를 찍었다면, 서버 쪽 출력부터 확인해 주세요. 클라이언트 화면에 결과를 출력하는 코드와 서버의 진단 출력은 구분해야 해요.
점검용 클라이언트가 끝나지 않는다면 연결을 닫았는지도 보세요. 공식 문서는 client.close()로 연결과 자식 프로세스를 정리하며, 중간에 오류가 날 수 있는 코드는 finally에서 닫도록 안내해요. 한 번의 점검이 끝났는데 서버 프로세스가 계속 남아 있으면 다음 시도의 기록까지 뒤섞일 수 있어요.
팀에 연결 설정을 넘길 때는 사용한 버전과 도구 목록 확인 결과를 함께 남겨 두세요. 실행 명령만 적힌 메모보다, 다음 사람이 같은 단계까지 도달했는지 비교하기 쉬워요. 호스트별 설정 양식은 해당 호스트의 현재 안내를 확인해서 채우면 돼요.
참고한 자료
- MCP TypeScript SDK 2.3.1 릴리스 https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/v2.3.1 (확인일 2026-10-09)
- 2.3.1 README의 패키지 구성 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v2.3.1/README.md (확인일 2026-10-09)
- 공식 첫 클라이언트 연결 튜토리얼 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v2.3.1/docs/get-started/first-client.md (확인일 2026-10-09)
- 공식 첫 서버 튜토리얼 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v2.3.1/docs/get-started/first-server.md (확인일 2026-10-09)"