문서

처음부터 연결까지

Local MCP Workspace 설정, 전체 체인 검증, Secure Tunnel 시작, 자주 발생하는 문제 진단을 위한 실용 가이드입니다.

설치 및 머신 준비

데스크톱 앱이 운영 레이어를 관리하지만 시작할 Local MCP Runtime은 머신에 설치되어 있어야 합니다.

Tunnel Manager 설치공개 Stable Release가 준비되면 서명된 Windows Installer를 사용하세요. Landing Page와 Release Endpoint는 동일한 Version Metadata를 표시합니다.

MCP Runtime 준비대상 MCP Server에 필요한 Runtime을 설치합니다. Serena 기반 Project에서는 Tunnel Manager가 사용하는 Environment에서 Serena 명령을 찾을 수 있어야 합니다.

Project를 로컬에 유지Source Project는 머신에 남아 있고 Tunnel Manager는 Local MCP Process와 Secure Tunnel 연결만 조율합니다.

Profile 생성

Profile은 하나의 MCP Workspace에 대한 재사용 가능한 연결 정의입니다. Validation과 Runtime State를 명확하게 유지하려면 Project/Runtime 조합마다 하나의 Profile을 권장합니다.

권장 Profile 필드

Project FolderMCP Server가 작업할 Local Workspace입니다.

MCP Target 명령Tunnel Manager가 시작할 명령입니다. 예: 선택한 Project의 Serena MCP Server.

Tunnel Identity 및 Runtime KeyOpenAI Secure Tunnel Workflow용으로 발급된 값을 사용하고 민감한 값은 Local Control Layer에만 저장하세요.

Key 로드 실패 때문에 Profile을 중복 생성하지 마세요. 저장된 Credential 상태를 수정하고 기존 Profile을 다시 Validation하세요.

Start 전 Validation

Validation은 필수 Preflight 단계로 다뤄야 합니다. Configuration, Credential, Tunnel Identity, MCP Target, Local Runtime 검사를 모두 통과한 후 Start가 활성화되어야 합니다.

Profile configuration    PASS Runtime API key          PASS Tunnel ID                PASS MCP target               PASS Local runtime            READY

Process가 이미 실행 중이면 상태 인식 제어가 중복 Start를 막아야 합니다. 새 복사본을 실행하지 말고 기존 Process를 Stop 또는 Restart하세요.

ChatGPT 연결

Validation 통과 후 Profile을 Start하면 Tunnel Manager가 설정된 Local MCP Process를 실행하고 Secure Tunnel을 구성하며 Desktop UI에 연결 상태를 표시합니다.

Validation된 Profile 시작MCP Runtime과 Tunnel이 모두 정상 실행 상태가 될 때까지 기다립니다.

ChatGPT Connector 설정 열기Tunnel과 연결된 MCP Connector를 선택하거나 다시 연결합니다.

AI 활동 확인ChatGPT가 Local MCP Tool을 호출하면 Tunnel Manager가 Connected/Standby에서 AI Active로 전환되고 관련 Runtime Log를 스트리밍해야 합니다.

Serena Project 설정

Serena 기반 Project에서는 Project 수준 동작을 Project의 .serena 디렉터리에 두고 머신별 Override는 project.local.yml.

.serena/ ├── project.yml          # versioned project configuration └── project.local.yml    # machine-specific overrides

Trusted Project 요구사항

Serena는 Project의 activation_command 를 Project Path가 Serena Global Configuration에서 Trusted인 경우에만 실행합니다. Global 규칙보다 정확한 Project Path 또는 제한된 개발 디렉터리를 Trust하는 것이 좋습니다 ** rule.

trusted_project_path_patterns: - /home/your-user/dev/your-project

문제 해결

표시되는 Validation 상태부터 확인한 다음 Streaming Log를 점검하세요. 문제는 보통 연결 체인의 한 레이어에 국한됩니다.

API Key 누락 또는 중복

새 Key를 추가하기 전에 Profile이 기존 저장 Key를 로드하는지 확인하세요. Credential 변경 후에는 다시 Validation합니다.

Tunnel ID 오류

Tunnel이 의도한 Environment에 속하는지, Profile이 오래된 Identifier를 재사용하지 않는지 확인하세요.

Workspace를 찾을 수 없음

MCP Runtime이 실제 실행되는 머신에 Project Folder가 존재하는지 확인하세요. Remote Linux Workspace는 해당 Linux Host에서 유효한 Path를 사용해야 합니다.

Serena 미설치 또는 명령을 찾을 수 없음

동일한 User Environment에서 설정된 MCP Target을 수동 실행하세요. PATH/Runtime 설치를 수정한 뒤 Tunnel Manager를 다시 시도합니다.

Project가 Trusted가 아님

정확한 Project Path를 Serena Global trusted_project_path_patterns에 추가한 다음 Serena/Tunnel Process를 Restart하여 새 Global Configuration을 로드합니다.

Port가 이미 사용 중

먼저 기존 Process를 확인하세요. Server 중복 실행을 피하고 정상 Process를 재사용하거나 오래된 Process를 Stop한 뒤 Profile을 Restart합니다.

Tunnel 연결 끊김

Local Network 접근성, Profile Credential, Tunnel 상태를 확인합니다. Auto Recovery가 활성화되어 있다면 Live Log에서 Reconnect 진행 여부를 확인하세요.

버튼 비활성

현재 상태를 확인하세요. Process가 Starting 또는 Running 중이면 Start는 비활성화되어야 하며 호환되지 않는 상태 전환 중에는 Validate도 사용할 수 없을 수 있습니다.