MCP 서버 연동 방법은 AI 앱에 도구와 리소스, 프롬프트를 표준 프로토콜로 붙이는 작업입니다. Cursor와 Claude Desktop은 이 연결을 설정 파일 또는 확장 화면에서 관리합니다. 같은 프로토콜이라 앱이 달라도 서버 설정 항목은 비슷합니다. 처음에는 로컬 서버 하나부터 붙이는 편이 안전합니다.
도구는 tools/list로 목록을 확인하고 tools/call로 실행합니다. 연동 전에 실행 파일 경로, 환경 변수, 원격이면 URL과 헤더를 미리 맞춰 두면 연결 실패를 줄일 수 있습니다. 로컬 서버는 command와 args를, 원격 서버는 url을 준비합니다.
MCP 서버가 하는 일과 연동 전에 확인할 준비물
MCP 서버는 AI 앱에 도구와 리소스, 프롬프트를 표준 프로토콜로 노출합니다. 클라이언트는 서버가 연 기능을 같은 방식으로 찾고 호출하므로 앱마다 별도 플러그인을 새로 짤 필요가 없습니다.
연동 전에는 Node 또는 Python 런타임, 서버 패키지 이름, 필요한 API 키를 확인하십시오. 원격 서버라면 접속 URL과 인증 헤더도 함께 준비합니다. 로컬 실행이면 command와 args, 환경 변수 키 이름을 메모해 두면 Cursor와 Claude Desktop에 그대로 옮기기 쉽습니다.
준비물은 서버 README의 설치 명령과 환경 변수 표를 기준으로 모읍니다. API 키가 필요한 도구는 키를 발급받은 뒤에만 서버를 등록하십시오. 네트워크 제한이 있는 회사망이면 원격 url 허용 여부도 미리 확인합니다.
Cursor에서 MCP 서버를 등록하고 연결하는 방법
(출처: 개발동생)
Cursor는 Customize 페이지나 mcp.json으로 MCP를 설치하고 관리합니다. 로컬 서버는 command와 args로 등록하고 원격 서버는 url과 필요하면 headers로 등록합니다.
프로젝트 범위는 .cursor/mcp.json, 전역은 ~/.cursor/mcp.json을 씁니다. 두 파일을 합칠 때 이름이 같으면 프로젝트 설정이 우선합니다. 저장한 뒤에는 재시작해 command와 args, env를 다시 읽게 하십시오.
Customize에서 설치하면 전역 설정에 들어가는 경우가 많습니다. 팀과 공유할 서버만 프로젝트 .cursor/mcp.json에 두십시오. 이름은 영문으로 통일하면 충돌을 찾기 쉽습니다.
설정 파일에 서버를 추가하는 흐름
mcp.json의 mcpServers 아래에 서버 이름을 키로 두고 로컬이면 command와 args, env를 적습니다. npx로 띄우는 예시가 흔하며 패키지 이름과 실행 인자를 args 배열에 넣습니다. 키 이름은 중복되지 않게 정하십시오. 서버 키는 영문과 하이픈만 쓰는 편이 안전합니다.
원격이면 url을 넣고 인증이 필요하면 headers에 토큰을 둡니다. Customize 화면에서 설치한 항목도 같은 파일에 모입니다. 프로젝트 파일과 전역 파일이 겹치면 프로젝트 쪽 값이 이깁니다. env에는 비밀 키만 넣고 명령 인자로 토큰을 넘기지 마십시오.
연결 성공 여부와 도구 호출 확인
설정 저장과 재시작 뒤에 Cursor가 서버를 띄웠는지 상태 표시를 확인합니다. 오류가 있으면 명령 경로와 env, 원격이면 url을 다시 봅니다.
대화에서 해당 도구를 호출해 tools/call이 실제로 동작하는지를 확인하십시오. 도구 목록이 비면 tools/list가 실패한 것이므로 서버 로그를 엽니다. 같은 이름이 전역과 프로젝트에 있으면 프로젝트 설정이 우선하니 기대한 서버가 맞는지 파일 위치부터 대조합니다. 성공하면 채팅에서 도구 사용 허가를 묻는 경우가 있습니다.
호출이 거부되면 해당 도구의 입력 스키마가 맞는지부터 고칩니다. 인자가 비어 있거나 타입이 다르면 tools/call이 실패합니다.
Claude Desktop 등 다른 AI 도구와 MCP 연동하기
Claude Desktop은 Settings의 Extensions에서 검토된 확장을 설치할 수 있습니다. 수동이면 claude_desktop_config.json의 mcpServers에 command와 args를 넣고 앱을 재시작합니다.
연결 확인은 채팅창 + 버튼의 Connectors에서 서버와 도구를 보거나 Desktop Developer 설정과 MCP 로그로 합니다. Cursor와 같이 로컬은 command, 원격은 url 패턴을 따릅니다. 확장은 검토된 패키지라 권한이 비교적 분명합니다. 수동 json은 재시작 전까지 반영되지 않으니 창을 완전히 종료했다가 여십시오.
| 구분 | Cursor | Claude Desktop |
|---|---|---|
| 설정 위치 | 프로젝트 .cursor/mcp.json, 전역 ~/.cursor/mcp.json | claude_desktop_config.json, Settings > Extensions |
| 로컬 서버 | command, args, env | mcpServers의 command, args |
| 원격 서버 | url, headers | 확장 설치 또는 url |
| 연결 확인 | 재시작 후 도구 호출 | 채팅 +의 Connectors, MCP 로그 |
연동이 안 될 때 자주 나는 오류와 점검 순서
서버가 안 뜨면 명령이 PATH에 있는지, npx와 런타임이 설치되어 있는지부터 확인합니다. json 문법 오류, 잘못된 키 이름, 저장 후 미재시작이 흔합니다.
원격은 url 오타와 headers 누락을 의심하십시오. 로그에 tools/list 실패가 있으면 서버 프로세스가 종료된 상태일 수 있습니다. Cursor는 프로젝트 mcp.json이 전역보다 우선하므로 빈 설정이 전역 서버를 가리는지도 확인합니다. Claude Desktop은 확장과 json을 동시에 고치면 항목이 겹칠 수 있습니다.
한 번에 설정을 여러 곳 고치지 마십시오. Cursor 프로젝트 파일, 전역 파일, Claude 설정 순으로 하나만 바꿔 재시험합니다.
인증·권한·경로 문제부터 보는 법
API 키가 env에 없거나 이름이 다르면 도구 호출에 실패합니다. 실행 파일이 상대 경로면 작업 폴더가 달라져 실패하기 쉽습니다.
절대 경로 또는 PATH에 있는 명령을 쓰십시오. 원격 헤더의 Bearer 토큰이 만료되면 url은 맞아도 인증 오류가 납니다. macOS에서 앱이 네트워크나 파일 접근 권한을 막은 경우도 있습니다. Claude Desktop의 Connectors에 서버는 보여도 도구가 비면 권한 범위와 개발자 MCP 로그의 인증 메시지를 대조하십시오.
Windows에서는 실행 정책과 공백 있는 경로 인용을 확인합니다. WSL과 네이티브 경로를 섞으면 command가 파일을 찾지 못합니다.
MCP 서버 연동 정리와 업무에 바로 쓰는 팁
MCP 서버 연동은 Cursor의 mcp.json과 Claude Desktop의 설정 파일 또는 Extensions로 끝냅니다. 로컬은 command와 args, 원격은 url과 headers를 맞춘 뒤 재시작하고 tools/list와 tools/call로 동작을 확인합니다.
업무 자동화에는 파일 검색, 브라우저, 사내 API처럼 반복 작업을 서버로 분리해 두면 모델만 바꿔도 도구는 그대로 쓸 수 있습니다. 오류 시 인증, 경로, json 합치기 순서로 좁히십시오. 같은 서버를 여러 앱에 붙일 때는 command 줄을 복사하고 키 이름만 맞추십시오. 모델은 Cursor나 Claude로 바꿔도 도구 목록은 MCP 쪽이 유지합니다.
매일 반복하는 조회와 초안 작업을 도구로 고정하십시오. 프롬프트를 매번 새로 적을 필요가 줄어듭니다.
