[MCP] MCP 서버 연결하기 — Cursor · Claude Desktop · Claude Code에서 외부 MCP 서버 연결하기

1. MCP 클라이언트란

• MCP 서버에 연결해서 Tool을 호출하는 AI 애플리케이션
• 사용자가 직접 사용하는 도구이며, 내부적으로 MCP Client 모듈을 가지고 MCP Server와 통신

종류	예시
IDE	Cursor, Windsurf, VS Code
데스크탑 앱	Claude Desktop
CLI	Claude Code

 

2. mcp.json — 공통 연결 설정 파일

• MCP 서버 연결 정보를 관리하는 설정 파일
• 클라이언트마다 파일 위치와 이름은 다르지만 작성 형식은 동일

1) 기본 형식

{
  "mcpServers": {
    "서버이름": {
      "url": "<http://localhost:8090/sse>"
    }
  }
}

 

2) 서버 종류별 작성법

(1) SSE 방식 — 직접 만든 Spring AI 서버

{
  "mcpServers": {
    "my-spring-server": {
      "url": "<http://localhost:8090/sse>"
    }
  }
}

(2) npx 방식 — 공식 제공 서버

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ]
    }
  }
}

(3) 여러 서버 동시 연결

{
  "mcpServers": {
    "my-spring-server": {
      "url": "<http://localhost:8090/sse>"
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

 

3. Cursor에서 연결하기

1) mcp.json 위치

(1) 프로젝트 단위 — 해당 프로젝트에서만 동작

project-root/
└── .cursor/
    └── mcp.json

• 팀원과 공유 가능
• API 키 같은 민감 정보가 있으면 .gitignore에 추가

(2) 전역 — 모든 프로젝트에서 동작

# Mac / Linux
~/.cursor/mcp.json

# Windows
C:\\Users\\{사용자명}\\.cursor\\mcp.json

 

2) MCP 패널에서 확인

Settings (톱니바퀴) → MCP → 연결된 서버 목록 확인

• 서버 클릭 → Tools 탭에서 tools/list로 받아온 Tool 목록과 description 확인 가능
• 연결 상태는 서버 옆 아이콘으로 확인

상태	의미
🟢 초록	연결 성공, Tool 목록 수신 완료
🔴 빨강	연결 실패
🟡 노랑	연결 시도 중

 

3) 트러블슈팅

(1) ECONNREFUSED

Error: connect ECONNREFUSED 127.0.0.1:8090

원인	확인 방법	해결
서버 미실행	lsof -i :8090 (Mac) / netstat -ano	findstr :8090 (Windows)
포트 불일치	application.yml의 server.port 확인	mcp.json URL 포트와 맞추기
URL 오타	mcp.json의 url 확인	/sse 경로 포함 여부 확인

(2) 정상 연결 순서

1. ./gradlew bootRun 으로 서버 실행
2. 서버 로그에서 "Started Application on port 8090" 확인
3. Cursor MCP 패널에서 Refresh
4. 🟢 초록 상태 + Tool 목록 확인

(3) Output 로그 확인

View → Output → 드롭다운에서 "MCP" 선택

• 연결 시도 로그, JSON-RPC 메시지 raw 확인 가능

 

4. Claude Desktop에서 연결하기

1) 설정 파일 위치

• Claude Desktop은 mcp.json이 아닌 claude_desktop_config.json 파일로 관리한다.

# Mac
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows
C:\\Users\\{사용자명}\\AppData\\Roaming\\Claude\\claude_desktop_config.json

 

2) 설정 파일 작성법

• 작성 형식은 mcp.json과 동일

{
  "mcpServers": {
    "my-spring-server": {
      "url": "<http://localhost:8090/sse>"
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ]
    }
  }
}

 

3) 연결 확인

Claude Desktop 우측 하단 🔌 아이콘 클릭
→ 연결된 MCP 서버 목록 확인
→ 서버 클릭 시 Tool 목록 확인 가능

• 설정 파일 수정 후 Claude Desktop 재시작 필요
• 연결 성공 시 채팅창에서 🔧 아이콘으로 사용 가능한 Tool 확인 가능

 

4) 트러블슈팅

(1) 설정 변경 후 반영이 안 될 때

• Claude Desktop 완전 종료 후 재시작 (트레이 아이콘 우클릭 → Quit)
• JSON 문법 오류 확인 (쉼표 누락, 따옴표 오류 등)

(2) 로그 확인

# Mac
~/Library/Logs/Claude/mcp.log

# Windows
C:\\Users\\{사용자명}\\AppData\\Roaming\\Claude\\logs\\mcp.log

 

5. Claude Code에서 연결하기

1) 설정 방법

• Claude Code는 CLI 명령어로 MCP 서버를 등록한다.

(1) 서버 추가

# SSE 방식 (Spring AI 서버)
claude mcp add my-spring-server --url <http://localhost:8090/sse>

# npx 방식 (공식 서버)
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/username/projects

(2) 등록된 서버 목록 확인

claude mcp list

(3) 서버 삭제

claude mcp remove my-spring-server

 

2) 적용 범위 설정

# 현재 프로젝트에만 적용 (기본값)
claude mcp add my-spring-server --url <http://localhost:8090/sse> --scope project

# 모든 프로젝트에 적용
claude mcp add my-spring-server --url <http://localhost:8090/sse> --scope user

 

3) 연결 확인

# Claude Code 실행 후 /mcp 명령어로 연결 상태 확인
/mcp

• 연결된 서버 목록과 각 서버의 Tool 목록 출력
• 🟢 connected 상태면 정상

 

6. 외부 공식 MCP 서버 목록

서버	패키지	기능
파일시스템	@modelcontextprotocol/server-filesystem	로컬 파일 읽기/쓰기/탐색
Git	@modelcontextprotocol/server-git	Git 저장소 조회, 커밋 히스토리
GitHub	@modelcontextprotocol/server-github	GitHub API 연동
PostgreSQL	@modelcontextprotocol/server-postgres	DB 조회
Slack	@modelcontextprotocol/server-slack	Slack 메시지 조회·전송
Brave Search	@modelcontextprotocol/server-brave-search	웹 검색
Google Maps	@modelcontextprotocol/server-google-maps	지도, 장소 검색