MCP 서버 자체 설치하기: 세 가지 호스트, 세 가지 메커니즘, 주의사항

MCP 서버 설정은 여전히 JSON 파일을 수동으로 편집해야 하는 경우가 많습니다. 호스트마다 파일과 형식이 다르기 때문이죠. 이러한 불편함 때문에 개발자들은 유용한 서버를 실행하지 못하게 됩니다. 이 글에서는 세 가지 호스트, 각각의 설치 메커니즘, 그리고 자주 발생하는 함정들을 설명합니다.

세 가지 호스트, 세 가지 메커니즘

• VS Code: 실제 API가 있습니다 — registerMcpServerDefinitionProvider. package.json에서 프로바이더를 선언하고 런타임에 서버 정의를 반환합니다. VS Code는 동의 프롬프트를 표시합니다. 설정 파일 편집이 필요 없습니다. 가장 깔끔하지만 VS Code 확장을 배포해야 합니다.
• Cursor: 네이티브 API가 없습니다. .cursor/mcp.json에 직접 쓰되 루트 키는 mcpServers로 합니다.
• Claude Code: CLI를 사용하세요. 파일을 수동으로 작성하지 마십시오. 예를 들어 다음과 같이 실행합니다:
  claude mcp add --transport stdio --scope <user|local> --env … <name> -- node <path>

주의해야 할 여섯 가지 함정

1. 그 JSON 파일은 당신 것이 아닙니다. Cursor의 mcp.json은 사용자의 다른 서버들을 포함합니다. 읽어서, 항목을 병합하고, 관련 없는 키는 보존하세요 — 덮어쓰지 마십시오.
2. 손상된 파일에서도 버티십시오. 파일이 존재하지만 유효하지 않은 JSON인 경우, 비어 있는 것으로 간주하고 덮어쓰지 마십시오. 읽기/권한 오류도 마찬가지로 다시 던집니다. '읽을 수 없음'을 '아무것도 없음'으로 처리하면 설정이 손상됩니다.
3. 백업 후 원자적으로 쓰기. 기존 파일을 건드리기 전에 복사하고, 임시 파일에 쓴 후 대상 파일로 이름을 바꾸십시오. mcp.json이 반쯤 쓰이면 편집기가 망가집니다.
4. 두 번 설치해도 오류가 아니라 아무 일도 없어야 합니다. Claude CLI는 항목이 이미 존재하면 오류를 냅니다 — 따라서 remove 후 add 하세요. 파일 기반 호스트는 서버 이름을 키로 사용하여 교체합니다. 다시 실행해도 중복되지 않고 안정적으로 동작해야 합니다.
5. 범위가 모든 것을 바꿉니다. 사용자 수준 설치와 프로젝트 수준 설치는 설정 위치와 서버 요구 사항(예: 명시적 데이터 디렉터리 대 상향 검색)이 다릅니다. 신중하게 선택하십시오.
6. 최신 상태를 유지하는 것은 당신의 책임입니다. 등록된 버전과 배포한 버전이 차이가 날 수 있습니다. '설치된 것이 현재 번들 버전인가?'를 확인하고, 깔끔하게 재설치할 경로를 제공하세요. 하나의 버튼으로 상태(설치, 업데이트, 최신)를 표시합니다.

핵심 교훈: 수동 설정은 실패합니다. 인간이 스니펫을 붙여넣을 때 절대 경로, 올바른 범위, 환경 변수, 안전한 병합 방법을 모르기 때문입니다. 설치 코드는 이 모든 것을 알고 있습니다.