MCP 연동

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 연동의 장점

확장된 기능

외부 시스템 접근: 내장 기능으로는 사용할 수 없는 도구와 서비스에 Verdent을 연결합니다. 코딩 워크플로를 벗어나지 않고 데이터베이스를 조회하거나, 클라우드 서비스와 상호작용하거나, 프로젝트별 API와 연동할 수 있습니다.

맞춤 도구 개발: 프로젝트의 고유한 요구사항에 맞춘 MCP 서버를 만들 수 있습니다. 사내 도구, 독점 API, 도메인 특화 시스템을 위한 전문 연동을 구축합니다.

상호운용성

생태계 활용: 성장 중인 MCP 생태계를 활용합니다. 커뮤니티에서 개발한 MCP 서버는 인기 도구와 서비스를 위한 사전 구축 연동을 제공합니다.

표준화된 프로토콜: MCP은 도구 연동을 위한 일관된 인터페이스를 제공하므로, 새로운 기능이 Verdent의 기존 도구 시스템과 매끄럽게 통합됩니다.

워크플로 자동화

원활한 연동: MCP 서버는 Verdent의 도구 세트 일부가 됩니다. 에이전트가 적절할 때 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 설정 패널에서 연결 상태를 모니터링합니다.

도구 새로고침: 설정 변경 또는 연결 문제 후 서버에서 사용할 수 있는 도구를 다시 검색하려면 새로고침 버튼을 선택합니다.

MCP 설정

기본 설정

위치: 프로젝트 루트의 .mcp.json 또는 ~/.verdent/mcp.json(전역)

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    }
  }
}

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

{
  "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 플러그인과 확장

사용 가능한 플러그인

MCP 플러그인은 일반적인 도구와 서비스를 위한 사전 구축 연동을 제공합니다. 현재 사용 가능한 항목은 mcp.so/servers의 커뮤니티 레지스트리 또는 공식 MCP 서버 저장소에서 확인하세요.

일반적인 플러그인 범주:

• 데이터베이스 연동: 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 프로토콜 사양을 구현하고, Verdent이 호출할 수 있는 도구 기능을 노출합니다. 구현 세부 사항과 SDK는 Model Context Protocol 사양을 참고하세요.

맞춤 서버 사용 사례:

• 사내 API 연동: 회사 전용 API와 서비스에 연결
• 레거시 시스템 브리지: Verdent이 레거시 인프라와 상호작용할 수 있게 함
• 전문 데이터 소스: 독점 데이터베이스 또는 데이터 웨어하우스에 접근
• 워크플로 자동화: 맞춤 빌드, 배포 또는 테스트 파이프라인 트리거

연동 패턴

워크스페이스 수준 설정: MCP 서버는 프로젝트별 연동을 위해 워크스페이스 수준에서 설정할 수 있으며, 팀이 버전 관리를 통해 MCP 설정을 공유할 수 있습니다.

도구 상호운용성: MCP에서 제공하는 도구는 Verdent의 내장 도구(file_read, bash, spawn_subagent)와 매끄럽게 통합되어 여러 도구 유형을 조합한 복잡한 워크플로를 지원합니다.

Desktop 전용 MCP 기능

프로젝트별 설정

멀티 Worktree MCP

MCP 서버는 worktree 전반에서 동작합니다.

• 공유 서버: 모든 worktree가 공유하는 기본 워크스페이스 MCP 설정
• 격리된 작업: 각 worktree는 별도의 MCP 세션 상태를 유지
• 병렬 접근: 여러 worktree가 같은 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 파이프라인 모니터링

시나리오: 변경 사항을 배포하기 전에 빌드 상태를 확인합니다.

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.json의 인증 자격 증명을 확인합니다
• MCP 서버가 실행 중이고 접근 가능한지 확인합니다
• 설정 파일 문법을 검증합니다

권한 오류:

• API 키 또는 자격 증명에 필요한 권한이 있는지 확인합니다
• 서비스 할당량 또는 속도 제한을 확인합니다
• 방화벽 규칙이 MCP 트래픽을 허용하는지 확인합니다

도구 호출 문제:

• MCP 서버가 예상 도구를 올바르게 노출하는지 확인합니다
• 도구 매개변수 형식이 서버 요구사항과 일치하는지 확인합니다
• 오류 세부 사항은 MCP 서버 로그를 검토합니다

도움 받기

지원 채널:

• Verdent 지원: support@verdent.ai
• MCP 프로토콜 문서
• Verdent Discord 커뮤니티

진단 정보: MCP 문제를 보고할 때 다음을 제공하세요.

• MCP 서버 유형과 버전
• 설정 세부 정보(자격 증명 제거)
• 채팅 기록의 오류 메시지
• MCP 서버 로그(접근 가능한 경우)

FAQ