MCP

MCP Starter Kit 시작 가이드: 백엔드 API를 AI 에이전트에 안전하게 브리지하기

MCP Starter Kit은 이미 백엔드 API를 보유한 개발자가 Claude나 ChatGPT가 호출할 수 있는 안전한 MCP 서버를 빠르게 구축하는 데 가장 적합하지만, 시작 전에 TLS 호스팅 조건을 갖추고 .env를 직접 작성하며 도구를 구현해야 합니다.

Official source · GitHub - fdhhhdjd/MCP-STARTER-KIT: Build a secure, production-ready MCP server for any project

Install

npm install && npm run build

MCP Starter Kit는 프로젝트에 종속되지 않는 스캐폴드로, 어떤 프로젝트든 안전하게 배포 가능한 MCP(Model Context Protocol) 서버를 구축할 수 있게 해줍니다: 각 도구는 하나의 백엔드 엔드포인트에 매핑되고, API key + scopes로 인증하며, AI 에이전트(Claude Desktop/Web, ChatGPT 또는 자체 구축 에이전트)를 여러분의 백엔드 API에 브리지합니다. 단순히 기존 도구를 사용해 보고 싶다면 적합하지 않습니다. 백엔드 API를 보유하고, 서비스를 호스팅할 수 있으며, 빌드 및 배포 과정을 감수할 수 있어야 합니다.

누구에게 적합한가

  • 자신의 백엔드 API를 Claude, ChatGPT 등의 에이전트가 안전하게 호출하도록 하고 싶은 개발자.
  • 각 엔드포인트에 하나의 도구를 대응시키고, API key + scopes로 권한을 제어해야 하는 팀. 기본값은 읽기 전용이며, 쓰기 권한 scope를 명시적으로 추가해야만 쓰기가 가능합니다.
  • 온라인(Streamable HTTP, 다중 클라이언트)과 Claude Desktop(stdio) 두 가지 접속 방식, 또는 스테이트리스 OAuth 2.0(PKCE S256)과 헤더 API key 두 가지 인증 방식이 필요한 경우.
  • 부적합한 경우: 백엔드 API가 없거나, TLS 호스팅 조건이 없거나, 코드와 설정 변경을 전혀 하고 싶지 않은 사용자. 공식 문서에는 호스팅 비용, 실행 환경 요구 사항의 세부 내용이 명시되어 있지 않으므로, 이러한 미확인 사항은 직접 확인해야 합니다.

3분 만에 첫 시도 완료하기

첫 시도는 스캐폴드 자체를 빌드하고 연결하는 것부터 시작하는 것을 권장합니다(실제 엔드포인트 호출은 도구를 구성한 후에 이루어집니다):

  1. 사전 준비: Node/npm이 설치되어 있어야 하며, TLS 사용 가능한 도메인을 준비합니다(서비스는 TLS 뒤에서 호스팅되어야 하며, 경로는 /mcp입니다).
  2. README의 템플릿 경로에 따라: templates/로 이동한 뒤 gitignore를 .gitignore로 이름을 바꾸고, __PROJECT__를 프로젝트 이름으로 교체하며, .env를 작성하고, src/server.ts에 도구를 추가합니다.
  3. 공식에서 제공하는 빌드 명령을 실행합니다:
npm install && npm run build
  1. TLS 뒤에서 호스팅한 뒤(경로 /mcp), mcp-remote로 Claude Desktop에서 연결하여 한 번 검증합니다(연결 초기화는 저위험 작업이며, key는 initialize 시점에 백엔드에서 검증됩니다):
npx -y mcp-remote https://<domain>/mcp --header "Authorization: Bearer <key>"

성공 신호: 클라이언트가 initialize를 완료하고 백엔드 key 검증이 통과되는 것입니다(공식 문서는 이 검증이 초기화 시점에 미인증 요청을 차단한다고 명시하고 있습니다). Claude Web은 커스텀 커넥터를 사용하며, URL은 /mcp, 헤더는 x-api-key입니다. 참고: 위 명령에서 <domain>, <key>는 실제 값으로 교체해야 하는 부분입니다. .env에 키를 입력하는 것은 로컬 상태 쓰기 작업이며, 읽기 전용 작업이 아닙니다.

사용 사례

  1. Claude Desktop으로 백엔드의 읽기 전용 엔드포인트 호출: 위의 기본 경로에 따라 빌드와 TLS 호스팅을 마친 뒤, Claude Desktop에서 mcp-remote를 통해 Bearer key로 /mcp에 연결합니다. 기본값이 읽기 전용이므로, 쓰기 scope를 명시적으로 추가하지 않는 한 호출은 백엔드 쓰기 작업을 유발하지 않습니다. 이는 공식이 선언한 동작이지만, 제로 리스크를 의미하지는 않으며, 키는 여전히 백엔드에서 검증되고 mcp-remote를 통해 전달됩니다.
  2. Claude Web 커스텀 커넥터로 동일한 서비스에 접속: Claude Web에서 커스텀 커넥터를 구성하고, URL /mcp와 x-api-key 헤더를 사용합니다. 연결이 설정되는 단계까지는 확인할 수 있습니다. 특정 도구의 출력 형식은 src/server.ts에서 해당 도구를 어떻게 구현하느냐에 따라 달라지며, 공식 증거에는 구체적인 도구 예시가 없으므로 더 이상 예측할 수 없습니다.

사용 경계

  • 읽기/쓰기 특성: 템플릿은 기본적으로 읽기 전용이며, 쓰기 기능은 scope를 명시적으로 추가해야 합니다. 쓰기 작업은 원격 쓰기이므로 실행 전에 부작용을 확인해야 합니다.
  • 자격 증명: API key(또는 선택 사항인 스테이트리스 OAuth 2.0 PKCE S256)로 인증합니다. .env에 구성을 작성해야 하며, 이는 로컬 민감 상태에 해당합니다.
  • 로그: 감사 로그는 stderr로 출력되고, stdout은 JSON-RPC에 예약되어 있으므로, 디버깅 시 채널의 차이에 주의해야 합니다.
  • 보안 메커니즘의 경계: key는 initialize 시점에 검증되어 미인증 악용을 차단합니다. 읽기 전용 기본값과 initialize 검증은 쓰기 작업을 수행하지 않고 키를 검증한다는 의미일 뿐, 네트워크에 연결되지 않거나 다른 프라이버시 경계가 없다는 뜻은 아닙니다.
  • 미확인 정보: 공식 증거에는 각 클라이언트의 상세한 구성 파일 형식, 호스팅 플랫폼 요구 사항, 구체적인 엔드포인트/도구 구현 예시가 명시되어 있지 않습니다. 이러한 사항은 첫 사용 전에 직접 리포지토리를 참조하여 확인해야 합니다.