AI 클라이언트 연동 (IDE Integration)
ServBay는 내장된 MCP 서버를 당신이 주로 사용하는 다양한 AI 클라이언트와 한 번의 클릭으로 연동할 수 있습니다. ServBay가 각 클라이언트의 MCP 설정을 자동으로 입력하기 때문에, 직접 설정 파일을 수정할 필요가 없습니다. 본 문서에서는 연동 방법, 지원 클라이언트 목록, 그리고 각 클라이언트별 연동 방식을 안내합니다.
선행 조건
- ServBay가 설치되어 실행 중이어야 합니다.
- 대상 AI 클라이언트가 설치되어 있어야 하며(ServBay가 해당 클라이언트의 설정을 통해 연동 가능 여부를 판단함).
원클릭 연동
**ServBay 설정(Settings) → AI 클라이언트 연동(IDE Integrations)**으로 이동해, 클라이언트 목록에서 원하는 클라이언트를 선택한 뒤 연동(Integrate) 버튼을 클릭하세요. ServBay는 다음을 자동으로 수행합니다.
- 배포판에 포함된
servbay-mcp실행 파일 위치를 자동으로 찾습니다(별도 설치 불필요). - 대상 클라이언트의 설정 규격에 따라 MCP 설정을 기록합니다(오직
servbay노드만 추가/업데이트하며, 기존 MCP 설정은 그대로 보존됨). - 연동 상태를 표시합니다.
연동을 취소하려면 제거(Remove) 버튼을 클릭하면 됩니다.
연동 상태
각 클라이언트에는 "현재 ServBay 인스턴스"와의 연동 상태가 다음 중 하나로 표시됩니다.
| 상태 | 의미 |
|---|---|
| 연동 완료 | 클라이언트가 현재 PC의 ServBay servbay-mcp를 참조하고 있음 |
| 연동 완료(다른 경로) | 클라이언트에 servbay가 등록되어 있지만 다른 경로(예: 다른 ServBay 인스턴스)를 가리킴 |
| 미연동 | 클라이언트를 감지했으나 아직 연동되지 않음 |
| 미감지 | 해당 클라이언트를 PC에서 찾지 못함 |
지원 클라이언트 및 연동 방식
| 클라이언트 | 연동 방식 | 설정 위치 |
|---|---|---|
| Claude Code | 공식 CLI: claude mcp add --scope user --transport stdio servbay -- <bin> | Claude Code 사용자 MCP 설정 |
| Codex | 공식 CLI: codex mcp add (CLI 사용 불가 시 ~/.codex/config.toml 직접 추가) | Codex 설정 |
| Cursor | ~/.cursor/mcp.json에 최상위 mcpServers 추가 | ~/.cursor/mcp.json |
| VS Code / GitHub Copilot | 사용자별 mcp.json에 최상위 servers(type: stdio) 추가 | VS Code 사용자 mcp.json |
| Claude Desktop | claude_desktop_config.json에 최상위 mcpServers 추가 | claude_desktop_config.json |
설정 스키마 차이
클라이언트별 MCP 설정 파일의 최상위 키는 상이합니다: VS Code는 servers, Cursor/Claude Desktop은 mcpServers를 사용합니다. ServBay가 각 클라이언트의 규격에 맞춰 자동으로 올바른 키로 입력하므로 직접 구분할 필요가 없습니다.
연동 확인 방법
연동 이후, 해당 AI 클라이언트에서 환경과 관련된 요청(예: "현재 ServBay에서 실행 중인 서비스 목록 보여줘")을 한번 시도해 보세요. AI가 실제 서비스 목록을 반환하면 연동이 완료된 것입니다.
자주 묻는 질문 (FAQ)
- Q: 연동 시 기존 MCP 설정이 덮어써지나요?
- A: 아닙니다. ServBay는
servbay노드만 추가/수정하며, 기존에 설정된 다른 MCP 서버 정보는 유지됩니다.
- A: 아닙니다. ServBay는
- Q: 클라이언트가 '미감지'로 표시됩니다.
- A: 해당 클라이언트가 아직 PC에 설치되지 않았거나 한 번도 실행된 적이 없는 경우입니다. 설치 후 최초 실행한 뒤 연동해 주세요.
- Q: 연동 후 AI 호출이 실패합니다.
- A: ServBay가 정상적으로 실행 중인지 확인하세요. Claude Code/Codex에 CLI 기반 연동을 사용하는 경우, 공식 CLI가 사용 가능한지도 확인 바랍니다. 문제가 지속될 경우 제거 후 재연동을 시도해 볼 수 있습니다.
- Q: 연동 이후 추가로 권장하는 작업이 있나요?
- A: AI 규칙을 추가 설치해 두면 AI가 ServBay MCP를 더 효과적으로 사용할 수 있도록 안내할 수 있습니다.
요약
"AI 클라이언트 연동" 기능을 활용하면 ServBay MCP를 주요 AI 도구에 원클릭으로 연결할 수 있습니다. 기존 설정을 건드리지 않고 손쉽게 통합할 수 있으며, AI 규칙이 더해지면 AI가 로컬 개발 환경을 자연스럽게 제어할 수 있습니다.
