Model Context Protocol을 로컬에서 실행하기
이 페이지를 사용하여 추출한 TypeScript MCP 서버를 실행하고 날씨 도구와 리소스를 MCP Inspector에서 시도해볼 수 있습니다. 서버는 표준 입출력을 통해 클라이언트와 통신하므로, 프로젝트 페이지나 애플리케이션 포트를 열지 않고 클라이언트가 접속할 때까지 기다립니다.
먼저 준비할 것
Node 24를 설치합니다. MCP Inspector는 최소 Node 버전을 요구하고 있으며 (작성 시점 기준 22.19), Node 24는 이 최소 요구사항을 충족하는 반면 구 버전의 LTS 릴리스는 테스팅 UI를 시작하지 못할 수 있습니다.
이 프로젝트는 API 키나 .env 파일이 필요하지 않습니다. MCP 클라이언트는 서버를 자식 프로세스로 실행하므로, 서버가 실행되는 Node 버전과 환경은 머신에서 이를 실행하는 것에서 나옵니다.
.env 파일도 필요 없습니다. 이 서버는 웹 페이지를 열지 않는다는 점이 조금 의외인데요. 클라이언트를 기다리면서 조용히 있다 보니 처음 실행했을 때 저도 완전히 헷갈렸습니다. 서버 설치 및 복구
package.json이 있는 추출한 서버 폴더에서 터미널을 엽니다.
$ cd path-to-your-downloaded-project
$ npm ci
$ npm install --save-dev tsx마지막 명령어는 TypeScript 파일을 실행하는 도구인 tsx를 기록합니다. 추출한 "start": "tsx server.ts" 스크립트가 이를 요구합니다.
표준 입출력 서버를 바로 시작할 수 있습니다.
$ npm start브라우저 URL을 출력하지 않고 MCP 클라이언트가 접속할 때까지 기다립니다. Inspector를 시작하기 전에 Ctrl+C로 중지합니다.
npm ci를 실행하고, TypeScript 파일을 실행하는 tsx 도구를 추가한 다음, npm start를 시도합니다. 터미널이 조용해지면 뭔가 잘못된 게 아닙니다. 서버가 클라이언트와 대화할 때까지 기다리고 있는 거예요. 누가 설명해주기 전까지 저는 서버를 세 번이나 다시 시작했었습니다! MCP Inspector로 테스트하기
같은 프로젝트 폴더에서 공식 MCP Inspector를 실행합니다.
$ npx @modelcontextprotocol/inspector npx tsx server.ts첫 npx는 Inspector를 다운로드하고 시작하며, 일회성 설치 권한을 요청할 수 있습니다. 패키지가 @modelcontextprotocol/inspector인지 확인한 후 수락하고, 반복 가능한 팀 사용을 위해서는 가장 최신 릴리스에 무제한 의존하기보다는 검토된 버전을 고정하세요. Inspector는 그 다음 npx tsx server.ts를 표준 입출력 자식 프로세스로 서버를 실행합니다. 웹 UI는 자신의 로컬 포트에서 실행되며, 서버와의 표준 입출력 연결과는 별개입니다. 터미널에 출력된 로컬 URL을 열면 되며, 자동으로 열리지 않으면 직접 엽니다.
Inspector에서 서버에 연결하고, 도구와 리소스를 나열한 다음, 코스에서 사용된 입력 중 하나로 날씨 도구를 호출합니다. 도구 사용 챕터에서는 이 같은 도구 정의가 모델에 무엇을 제공하는지 설명합니다. 테스트하는 동안 터미널을 열어둔 후, Ctrl+C로 Inspector와 자식 서버를 중지합니다.
다른 MCP 클라이언트 연결하기
데스크톱 클라이언트는 같은 표준 입출력 서버를 실행하기 위한 실행 명령어와 인수가 필요합니다. 먼저 추출한 프로젝트 폴더와 그 server.ts 파일의 절대 경로를 복사합니다. 이 프로세스 계약으로 클라이언트를 구성하며, 두 예시 경로 모두 바꿉니다.
command: npm
arguments:
- --prefix
- /absolute/path/to/project
- exec
- --
- tsx
- /absolute/path/to/project/server.ts--prefix 값은 npm이 데스크톱 클라이언트가 다른 작업 디렉터리에서 시작되더라도 그 프로젝트에 설치된 tsx 의존성을 사용하도록 합니다. 클라이언트가 앞에 npm --prefix 없이 tsx를 자체적으로 실행하도록 구성되어 있다면, 대신 전역 설치와 클라이언트의 PATH에 의존하는데, 이는 터미널의 경로와 다른 경우가 많습니다. 각 인수를 별개의 항목으로 유지하여 공백을 포함한 경로가 하나의 값으로 남도록 합니다. URL이나 포트를 추가하지 마세요. 이 서버는 표준 입출력으로 통신합니다.
이렇게 서버를 연결하는 것이 데스크톱 클라이언트가 모델에 도구를 제공하는 방식입니다. 에이전트 챕터에서는 이러한 도구를 사용하는 루프를 다룹니다.
클라이언트 구성 형식이 다르므로, 그 명령어와 인수를 클라이언트의 현재 MCP 설정 지침에 있는 필드에 매핑합니다. 구성을 변경한 후 클라이언트를 다시 시작합니다. 다른 프로젝트를 다운로드할 필요가 없습니다. 이미 테스트한 추출한 서버에 연결하면 됩니다.
npm으로 설정하고, 두 절대 경로를 채운 문서화된 인수를 추가한 후 클라이언트를 다시 시작합니다. Inspector가 테스트한 같은 추출한 서버를 재사용하고 있으므로, 거기서 작동했다면 서버 쪽은 이미 증명되었습니다. 문제 해결
tsx: command not found: 프로젝트 폴더에서 npm install --save-dev tsx를 실행합니다. 데스크톱 클라이언트의 경우, 명령어가 npm이고 인수가 --prefix 다음에 절대 프로젝트 경로로 시작하는지 확인합니다.
Inspector가 Node 버전을 거부합니다: Node 24를 설치하고, node --version으로 확인한 다음, 터미널을 다시 엽니다.
npm start가 멈춘 것처럼 보입니다: 이는 클라이언트를 기다리는 표준 입출력 서버의 예상된 동작입니다. Inspector를 사용해 상호작용합니다.
Inspector에 도구가 표시되지 않습니다: 터미널에서 TypeScript 또는 연결 오류를 확인하고 최종 명령어가 npx tsx server.ts로 끝나는지 확인합니다.
tsx가 누락되면 설치하고, Inspector가 시작을 거부하면 Node 24로 이동하고, 조용한 서버는 깨진 게 아니라 기다리는 서버라는 것을 기억하세요. 이 페이지의 거의 모든 문제가 이 세 가지 중 하나입니다.