> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/documentation/ko/user-guide/mcp-integration.md).

# MCP 통합

> MCP(Model Context Protocol)는 AI 에이전트가 외부 도구와 데이터 소스에 접근할 수 있도록 하는 프로토콜입니다. Orbitron은 MCP 서버와 통합하여 GitHub, Slack, PostgreSQL 등 다양한 외부 서비스에 연결함으로써 AI 에이전트의 기능을 확장합니다.

***

## 🔗 MCP란?

Model Context Protocol을 통해 AI 에이전트는 다음을 수행할 수 있습니다:

* 외부 API 및 서비스 접근
* 파일 시스템 작업 수행
* 데이터베이스 쿼리
* 서드파티 플랫폼과 상호작용
* 브라우저 자동화 작업 실행
* 확장 가능한 도구 통합을 통한 더 많은 기능

***

## ⚡ 주요 기능

### 🔌 1. 세 가지 서버 타입

Orbitron은 세 가지 타입의 MCP 서버를 지원합니다:

* **stdio**: 표준 입출력을 통해 로컬 프로세스와 통신 (예: npx 명령어)
* **sse**: Server-Sent Events를 통해 원격 서버와 통신
* **streamable-http**: Streamable HTTP 프로토콜을 통한 통신

***

### ✅ 2. 자동 승인 (계획 중)

특정 도구를 실행할 때마다 수동 승인 없이 실행되도록 구성할 수 있는 기능이 계획되어 있습니다:

```json
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem"],
    "autoApprove": ["read_file", "list_directory"]
  }
}
```

> **참고**: autoApprove 필드는 설정 파일에 저장되지만, 현재 버전에서는 실제로 적용되지 않습니다. 향후 업데이트에서 지원될 예정입니다.

***

## ⚙️ 설정

### 📁 설정 파일 위치

MCP 서버는 `~/.orbitron.json`에서 설정됩니다:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "type": "stdio"
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "type": "stdio"
    },
    "my-remote-server": {
      "type": "sse",
      "url": "https://my-server.com/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
```

***

### 📋 설정 구조

각 MCP 서버는 다음 속성을 가질 수 있습니다:

* **command**: 실행할 명령어 (stdio 타입용)
* **args**: 명령어 인자 (stdio 타입용)
* **env**: 환경 변수 (키-값 쌍, 자동으로 대문자로 정규화됨)
* **type**: 서버 타입 ("stdio", "sse", 또는 "streamable-http")
* **url**: 서버 URL (sse 타입용)
* **headers**: HTTP 헤더 (sse 타입용)
* **disabled**: 서버 비활성화 여부
* **autoApprove**: 자동 승인할 도구 이름 배열

***

## 🖥️ MCP 서버 관리

### 💻 MCP TUI 제공

Orbitron은 MCP 서버 관리를 위한 다이얼로그들을 제공합니다.

***

### 📋 MCP 서버 목록 다이얼로그

**열기**

`/mcp`를 입력하면 다이얼로그가 열립니다.

* **이동/선택**: `↑`/`↓` 화살표 키로 서버 간 이동
* `Enter`: 서버 연결 테스트
* `t`: 서버 활성화/비활성화 토글
* `e`: 서버 설정 편집
* `d`: 서버 삭제
* `a`: 새 서버 추가
* `Esc`: 대화상자 닫기

**서버 상태 표시기 (v0.1.11+)**

서버 목록 다이얼로그의 TUI는 실시간 업데이트되는 색상 코드 상태 표시기를 보여줍니다:

* **● 초록색 (ready)**: 서버가 로드되어 준비 완료
* **● 노란색 (loading)**: 서버가 현재 로딩 중
* **● 빨간색 (failed/timeout)**: 서버 로드 실패 또는 타임아웃
* **● 회색 (disabled)**: 서버가 비활성화됨
* **● 파란색 (initializing)**: 서버 초기화 중

***

### ➕ MCP 서버 추가 다이얼로그

**열기**

MCP 서버 목록 다이얼로그(`/mcp`)에서 `a` 키를 누르면 서버 추가 다이얼로그가 열립니다.

**JSON 설정 입력**

```json
// JSON 설정 입력 예시
{
  "my-server": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-package"],
    "env": {
      "API_KEY": "your-api-key"
    }
  }
}
```

**저장 및 테스트**

`Ctrl+S`를 눌러 저장하거나 `Ctrl+T`를 눌러 저장 전 모든 서버를 테스트합니다.

***

### 🌐 조직 MCP 설정 공유

Orbitron Web에서 등록한 조직 MCP 설정을 터미널에서 쉽게 확인할 수 있습니다.

**열기**

`/shared-mcps`를 입력하면 조직 공유 MCP 설정 목록이 표시됩니다.

**기능**

* 조직에서 공유한 MCP 서버 설정 목록 확인
* 원하는 설정을 선택하여 클립보드에 복사 또는 JSON 파일로 다운로드

> 💡 **Tip**: Orbitron Web의 MCP 관리 메뉴에서 조직 공유 MCP 설정을 등록하면, 조직의 모든 멤버가 `/shared-mcps` 명령어를 통해 동일한 MCP 설정을 쉽게 확인할 수 있습니다.

***

### ✓ 설정 검증

서버를 추가하거나 업데이트할 때 Orbitron은 다음을 검증합니다:

* JSON 구문 정확성
* 서버 타입 (설정에서 자동 추론)
* 각 서버 타입별 필수 필드:
  * stdio: `command` 필요
  * sse: `url` 필요

***

## 🔧 MCP 도구 작동 방식

### ⚙️ 도구 실행 흐름

1. AI 에이전트가 MCP 도구 사용 요청
2. 권한 확인 (자동 승인되지 않은 경우)
3. 클라이언트 연결 재사용 또는 생성
4. 재시도 메커니즘으로 도구 실행
5. AI 에이전트에 결과 반환

***

## 🔐 보안 및 권한

### 🛡️ 권한 시스템

모든 MCP 도구 실행은 권한 승인이 필요합니다:

* 도구 실행 전 사용자에게 프롬프트 표시
* 도구 이름, 작업 및 매개변수 표시
* 향후 `autoApprove`를 사용한 자동 승인 기능 지원 예정

***

## 🚀 고급 기능

### 📊 서버별 상태 추적 (v0.1.11+)

각 서버는 실시간으로 업데이트되는 자체 상태를 가집니다:

* 각 서버에 독립적인 상태
* TUI에서 시각적 피드백
* 문제가 있는 서버를 빠르게 식별 가능

***

### 📈 사용량 통계

Orbitron은 MCP 도구 사용량을 추적합니다:

* 도구별 호출 횟수 기록
* 자주 사용되는 도구 식별에 도움
* 최적화 결정에 유용

***

## 🔍 문제 해결

### ❌ 서버가 로드되지 않음

1. MCP 서버 목록 대화상자에서 서버 상태 확인 (색상 코드 표시기)
2. `Enter` 키를 사용하여 서버 테스트
3. 환경 변수가 올바르게 설정되었는지 확인 (대문자여야 함)
4. 상세한 오류 메시지는 로그 확인 필요
5. 필요한 패키지가 설치되었는지 확인 (npx 명령어용)

***

### ⏱️ 타임아웃 문제

서버가 지속적으로 타임아웃되는 경우:

* 개별 서버 타임아웃은 60초
* 전체 초기화 타임아웃은 10초 (MCPInitTimeout)
* 네트워크 연결 확인 (sse 타입용)
* 명령어/URL이 올바른지 확인
* 시스템 리소스 증가 고려

***

### 🚫 권한 거부

도구가 권한 오류로 실패하는 경우:

* 파일 시스템 권한 확인 (파일 작업용)
* API 토큰이 유효한지 확인 (서비스 통합용)
* 권한 프롬프트에서 승인했는지 확인

***

### 💾 캐시 문제

도구가 최근 변경 사항을 반영하지 않는 경우:

* 설정 해시 불일치로 캐시가 자동 무효화됨
* 필요한 경우 서버 수동 재로드
* 설정 파일이 제대로 저장되었는지 확인
* 비활성화된 서버 상태가 캐시에 추적됨 (v0.1.11+)