요즘 Cursor나 Claude Code 쓰면서 모델 컨텍스트 프로토콜(MCP) 연동하시는 분들 정말 많으시죠? 다양한 도구를 직접 AI 어시스턴트에 연결해 쓰는 재미가 쏠쏠하지만, 처음 설정하다 보면 원인 모를 버그로 막힐 때가 많습니다. 초보자분들이 직접 연동할 때 삽질을 줄일 수 있는 세 가지 팁을 나눕니다.

첫째, Cursor에서 원격 MCP 서버를 연결할 때 mcp.json 파일에 "type": "streamable-http"를 지정하면, CLI 에이전트가 이 설정을 인식하지 못하고 파일 자체를 누락시키는 버그가 있습니다. 이럴 때는 아래와 같이 타입을 단순 http로 바꿔서 작성해 보세요 ㅎㅎ

{
  "mcpServers": {
    "my-remote-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

또한 타사 어댑터 설정 중에 "type": "local"로 잡혀서 등록이 안 될 때도 있는데, 이때는 "type": "stdio"로 수동 변경해 주시면 아주 잘 작동합니다.

둘째, Claude Code는 문법이나 포맷 검증이 훨씬 까다로운 편이에요. 설정에 오타가 있거나 스키마가 안 맞으면 터미널 내 진단 명령어인 \doctor나 \mcp 유틸리티에서 바로 오류를 뱉어내니 꼭 확인해 보시는 게 좋습니다. 대신 Claude Code는 비밀키 노출을 막기 위해 ${VAR} 형태의 환경 변수 치환을 지원하기 때문에, 협업 프로젝트에 설정을 공유할 때 유용해요. 참고로 이제 SSE 대신 Streamable HTTP 사용이 공식 추천되고 있습니다.

마지막으로 Cursor를 쓰신다면 너무 많은 MCP 서버를 동시에 켜두지 마세요. 도구가 총 40개를 넘어가면 UI에 제대로 나타나지 않거나 씹히는 기능 제한이 있습니다. 에디터를 재시작할 때마다 채팅 창에서 일일이 켜줘야 하는 번거로움도 있으니, 평소에는 꼭 필요한 서버들만 간결하게 골라 켜두는 게 좋습니다~