# MCP 연동 (/ko/docs/verdent-manager/configuration/mcp)
> Model Context Protocol 서버와 플러그인으로 Verdent 확장하기
## MCP (Model Context Protocol)이란? [#mcp-model-context-protocol이란]
Model Context Protocol(MCP)은 외부 도구, 데이터 소스, 서비스에 연결해 Verdent의 기능을 확장하는 연동 시스템입니다.
**핵심 개념:**
MCP을 사용하면 Verdent이 내장 도구 세트를 넘어 다양한 시스템과 상호작용할 수 있으며, 다음과 원활하게 연동할 수 있습니다.
* 외부 API와 웹 서비스
* 데이터베이스 시스템
* 클라우드 플랫폼(AWS, Azure, GCP)
* 프로젝트 관리 도구
* CI/CD 파이프라인
* 사내 맞춤 도구
**아키텍처:**
MCP 서버는 Verdent과 외부 시스템 사이의 브리지 역할을 합니다. 각 MCP 서버는 코딩 세션 중 Verdent이 호출할 수 있는 특정 기능을 노출하며, `file_read` 또는 `bash` 같은 내장 도구와 비슷하게 동작합니다.
**설정 저장소:**
MCP 서버 설정은 `~/.verdent/mcp.json`에 저장되며 Settings 메뉴에서 관리합니다.
***
## MCP 연동의 장점 [#mcp-연동의-장점]
### 확장된 기능 [#확장된-기능]
**외부 시스템 접근:**
내장 기능으로는 사용할 수 없는 도구와 서비스에 Verdent을 연결합니다. 코딩 워크플로를 벗어나지 않고 데이터베이스를 조회하거나, 클라우드 서비스와 상호작용하거나, 프로젝트별 API와 연동할 수 있습니다.
**맞춤 도구 개발:**
프로젝트의 고유한 요구사항에 맞춘 MCP 서버를 만들 수 있습니다. 사내 도구, 독점 API, 도메인 특화 시스템을 위한 전문 연동을 구축합니다.
### 상호운용성 [#상호운용성]
**생태계 활용:**
성장 중인 MCP 생태계를 활용합니다. 커뮤니티에서 개발한 MCP 서버는 인기 도구와 서비스를 위한 사전 구축 연동을 제공합니다.
**표준화된 프로토콜:**
MCP은 도구 연동을 위한 일관된 인터페이스를 제공하므로, 새로운 기능이 Verdent의 기존 도구 시스템과 매끄럽게 통합됩니다.
### 워크플로 자동화 [#워크플로-자동화]
**원활한 연동:**
MCP 서버는 Verdent의 도구 세트 일부가 됩니다. 에이전트가 적절할 때 MCP 도구를 자동으로 사용하거나, 특정 작업을 위해 명시적으로 호출할 수 있습니다.
**컨텍스트 인식 작업:**
MCP 연동은 코드베이스 컨텍스트를 이해하므로, 현재 개발 상태를 바탕으로 외부 시스템과 지능적으로 상호작용할 수 있습니다.
***
## MCP 서버 설정하기 [#mcp-서버-설정하기]
### 설정 절차 [#설정-절차]
**MCP 설정 열기:**
1. Verdent에서 Settings 메뉴를 엽니다
2. **MCP Servers** 섹션으로 이동합니다
3. `~/.verdent/mcp.json` 설정을 확인하거나 수정합니다
**설정 파일:**
MCP 서버는 `~/.verdent/mcp.json` 파일을 통해 설정합니다. 이 파일은 서버 연결, 인증, 연동 매개변수를 정의합니다. 전체 스키마는 아래 **MCP 설정** 섹션을 참고하세요.
### 설정 관리 [#설정-관리]
**서버 추가:**
연결 세부 정보와 인증 자격 증명을 포함한 항목을 `mcp.json`에 추가해 새 MCP 서버를 설정합니다.
**여러 서버:**
Verdent은 여러 MCP 서버를 동시에 지원하므로 여러 외부 시스템과 동시에 연동할 수 있습니다.
**연결 테스트:**
개발 워크플로에서 사용하기 전에 MCP 서버 설정을 검증해 연결이 성공하는지 확인합니다.
### 서버 상태 [#서버-상태]
MCP 설정 패널에서 연결 상태를 모니터링합니다.
| 상태 | 설명 |
| ----------- | ---------------------- |
| **Success** | 서버가 연결되었고 도구를 사용할 수 있음 |
| **Failed** | 연결 오류(자세한 내용을 보려면 선택) |
| **Loading** | 서버 초기화 중 |
**도구 새로고침:**
설정 변경 또는 연결 문제 후 서버에서 사용할 수 있는 도구를 다시 검색하려면 새로고침 버튼을 선택합니다.
***
## MCP 설정 [#mcp-설정]
### 기본 설정 [#기본-설정]
**위치:** 프로젝트 루트의 `.mcp.json` 또는 `~/.verdent/mcp.json`(전역)
```json PostgreSQL Server
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://localhost:5432/myapp_dev"
]
}
}
}
```
```json GitHub Server
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
```json Multiple Servers
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://localhost:5432/myapp_dev"
]
},
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
**설정 키:**
* `mcpServers` - MCP 설정에 필요한 최상위 키
* `command` - 실행할 실행 파일(일반적으로 Node.js 패키지에는 `npx` 사용)
* `args` - 명령에 전달되는 인수(패키지 이름, 연결 문자열 등)
* `env` - 인증/설정을 위한 환경 변수
**MCP 더 알아보기:**
* [Model Context Protocol 사양](https://modelcontextprotocol.io/specification)
* [MCP 서버 레지스트리](https://mcp.so/servers) - 사용 가능한 MCP 서버 둘러보기
* [공식 MCP 서버](https://github.com/modelcontextprotocol) - PostgreSQL, GitHub, Filesystem 등
***
## MCP 플러그인과 확장 [#mcp-플러그인과-확장]
### 사용 가능한 플러그인 [#사용-가능한-플러그인]
MCP 플러그인은 일반적인 도구와 서비스를 위한 사전 구축 연동을 제공합니다. 현재 사용 가능한 항목은 [mcp.so/servers](https://mcp.so/servers)의 커뮤니티 레지스트리 또는 [공식 MCP 서버 저장소](https://github.com/modelcontextprotocol)에서 확인하세요.
**일반적인 플러그인 범주:**
* **데이터베이스 연동:** PostgreSQL, MySQL, MongoDB 쿼리 도구
* **클라우드 서비스:** AWS, Azure, GCP API 상호작용
* **개발자 도구:** GitHub, GitLab, Jira, Linear 연동
* **CI/CD 플랫폼:** Jenkins, GitHub Actions, CircleCI
* **모니터링 서비스:** Datadog, New Relic, Sentry
* **커뮤니케이션:** Slack, Discord, Microsoft Teams 알림
### 플러그인 설치 [#플러그인-설치]
**설치 방법:**
플러그인은 MCP Settings 인터페이스에서 설치하고 설정하며, 일반적으로 다음이 필요합니다.
* 플러그인 식별자 또는 소스
* 설정 매개변수
* 인증 자격 증명(해당하는 경우)
**의존성 관리:**
MCP 플러그인은 외부 서비스나 라이브러리에 대한 의존성이 있을 수 있습니다. 설치 과정은 가능한 경우 의존성 해결을 자동으로 처리합니다.
***
## 맞춤 MCP 서버 개발 [#맞춤-mcp-서버-개발]
### 맞춤 서버 만들기 [#맞춤-서버-만들기]
고급 사용자는 독점 도구나 도메인 특화 시스템과 연동하기 위해 맞춤 MCP 서버를 만들 수 있습니다.
**개발 방식:**
맞춤 MCP 서버는 MCP 프로토콜 사양을 구현하고, Verdent이 호출할 수 있는 도구 기능을 노출합니다. 구현 세부 사항과 SDK는 [Model Context Protocol 사양](https://modelcontextprotocol.io/specification)을 참고하세요.
**맞춤 서버 사용 사례:**
* **사내 API 연동:** 회사 전용 API와 서비스에 연결
* **레거시 시스템 브리지:** Verdent이 레거시 인프라와 상호작용할 수 있게 함
* **전문 데이터 소스:** 독점 데이터베이스 또는 데이터 웨어하우스에 접근
* **워크플로 자동화:** 맞춤 빌드, 배포 또는 테스트 파이프라인 트리거
### 연동 패턴 [#연동-패턴]
**워크스페이스 수준 설정:**
MCP 서버는 프로젝트별 연동을 위해 워크스페이스 수준에서 설정할 수 있으며, 팀이 버전 관리를 통해 MCP 설정을 공유할 수 있습니다.
**도구 상호운용성:**
MCP에서 제공하는 도구는 Verdent의 내장 도구(`file_read`, `bash`, `spawn_subagent`)와 매끄럽게 통합되어 여러 도구 유형을 조합한 복잡한 워크플로를 지원합니다.
***
## Desktop 전용 MCP 기능 [#desktop-전용-mcp-기능]
### 프로젝트별 설정 [#프로젝트별-설정]
| 설정 수준 | 위치 | 범위 |
| ------------ | --------------------- | ---------- |
| **전역** | `~/.verdent/mcp.json` | 모든 프로젝트 |
| **프로젝트** | 프로젝트 루트의 `.mcp.json` | 단일 프로젝트 |
| **Worktree** | 프로젝트에서 상속 | 프로젝트 설정 상속 |
### 멀티 Worktree MCP [#멀티-worktree-mcp]
MCP 서버는 worktree 전반에서 동작합니다.
* **공유 서버:** 모든 worktree가 공유하는 기본 워크스페이스 MCP 설정
* **격리된 작업:** 각 worktree는 별도의 MCP 세션 상태를 유지
* **병렬 접근:** 여러 worktree가 같은 MCP 서버를 동시에 사용할 수 있음
### 프로젝트 전환 [#프로젝트-전환]
프로젝트를 전환할 때:
* 현재 프로젝트의 MCP 서버가 로드됩니다
* 전역 MCP 서버는 계속 사용할 수 있습니다
* 이전 프로젝트의 MCP 연결은 백그라운드에서 유지됩니다
***
## MCP 워크플로 예시 [#mcp-워크플로-예시]
### 데이터베이스 쿼리 연동 [#데이터베이스-쿼리-연동]
**시나리오:** 데이터 문제 디버깅을 위해 프로덕션 데이터베이스를 조회합니다.
**MCP 방식:**
```
User: "Check the orders table for customer ID 12345"
Verdent: [Uses MCP database server to execute safe read-only query]
Results: 3 orders found for customer 12345
[Displays formatted results]
```
MCP 데이터베이스 서버가 인증, 쿼리 검증, 결과 형식화를 처리합니다.
### 클라우드 서비스 상호작용 [#클라우드-서비스-상호작용]
**시나리오:** 오류 확인을 위해 AWS Lambda 함수 로그를 확인합니다.
**MCP 방식:**
```
User: "Show me recent errors from the payment-processor Lambda function"
Verdent: [Invokes MCP AWS integration]
[Retrieves CloudWatch logs for specified function]
[Filters for ERROR level entries]
[Presents formatted error summaries]
```
MCP AWS 서버가 인증, API 호출, 로그 파싱을 관리합니다.
### CI/CD 파이프라인 모니터링 [#cicd-파이프라인-모니터링]
**시나리오:** 변경 사항을 배포하기 전에 빌드 상태를 확인합니다.
**MCP 방식:**
```
User: "Is the master branch build passing?"
Verdent: [Queries MCP CI/CD integration]
Build #245: ✓ Passed (2 minutes ago)
All tests passed, ready for deployment
```
MCP CI/CD 서버가 파이프라인 상태를 추적하고 실시간 피드백을 제공합니다.
***
## 보안 고려사항 [#보안-고려사항]
### 인증 및 권한 부여 [#인증-및-권한-부여]
**자격 증명 관리:**
MCP 서버는 외부 서비스 인증을 처리합니다. 자격 증명은 MCP 설정에 안전하게 저장되며 채팅 기록이나 코드에 노출되지 않습니다.
**권한 범위 지정:**
MCP 서버는 필요한 최소 권한으로 설정합니다. 가능한 경우 읽기 전용 접근을 사용하고, 파괴적인 작업은 제한하세요.
### 안전한 작업 [#안전한-작업]
**명령 검토:**
MCP 도구와 관련된 작업은 대화 기록에 표시되어 가시성과 제어권을 제공합니다.
**감사 로깅:**
MCP 서버 작업은 Verdent의 채팅 기록에 표시되어 외부 시스템 상호작용에 대한 감사 추적을 만듭니다.
***
## MCP 연동 문제 해결 [#mcp-연동-문제-해결]
### 일반적인 문제 [#일반적인-문제]
**연결 실패:**
* MCP 서버에 대한 네트워크 연결을 확인합니다
* `mcp.json`의 인증 자격 증명을 확인합니다
* MCP 서버가 실행 중이고 접근 가능한지 확인합니다
* 설정 파일 문법을 검증합니다
**권한 오류:**
* API 키 또는 자격 증명에 필요한 권한이 있는지 확인합니다
* 서비스 할당량 또는 속도 제한을 확인합니다
* 방화벽 규칙이 MCP 트래픽을 허용하는지 확인합니다
**도구 호출 문제:**
* MCP 서버가 예상 도구를 올바르게 노출하는지 확인합니다
* 도구 매개변수 형식이 서버 요구사항과 일치하는지 확인합니다
* 오류 세부 사항은 MCP 서버 로그를 검토합니다
### 도움 받기 [#도움-받기]
**지원 채널:**
* Verdent 지원: [support@verdent.ai](mailto:support@verdent.ai)
* [MCP 프로토콜 문서](https://modelcontextprotocol.io)
* [Verdent Discord 커뮤니티](https://discord.com/invite/NGjXEZcbJq)
**진단 정보:**
MCP 문제를 보고할 때 다음을 제공하세요.
* MCP 서버 유형과 버전
* 설정 세부 정보(자격 증명 제거)
* 채팅 기록의 오류 메시지
* MCP 서버 로그(접근 가능한 경우)
***
## FAQ [#faq]
MCP 서버 작업은 결과를 처리하는 모델에 따라 크레딧을 소비합니다. MCP 서버 자체는 크레딧을 직접 사용하지 않습니다.
아니요. MCP 서버는 프로젝트별이 아니라 사용자 수준에서 설정됩니다. 설정된 모든 서버는 모든 프로젝트에서 사용할 수 있습니다.
mcp.json의 자격 증명은 사용자의 컴퓨터에 로컬로 저장되며 Verdent 서버로 전송되지 않습니다. 민감한 값에는 환경 변수(`${VAR_NAME}`)를 사용하세요.
MCP 서버는 필요할 때 시작되고 세션 동안 실행됩니다. Verdent이 닫혀 있으면 리소스를 소비하지 않습니다.
MCP 서버는 사용자가 설정한 권한을 가집니다. 가능한 경우 읽기 전용 접근을 사용하고, 파괴적인 작업은 제한하세요.
Verdent에게 MCP 서버의 도구를 사용해 달라고 요청하세요. 응답이 성공하면 연결이 작동하는 것입니다. 문제가 발생하면 문제 해결 섹션을 확인하세요.