OpenBridge는 OpenCode와 Claude Code 세션이 서로 메시지를 주고받도록 하는 프로젝트별 로컬 MCP 브리지다. npm 패키지 하나로 설치하며 AgentAPI, Bun, 데이터베이스 서버, 호스팅 메시지 중계기는 필요하지 않다. 모델 추론은 각 에이전트가 설정한 모델 서비스를 계속 사용한다.
설치와 설정
설치 및 설정 안내에는 Node.js 22 이상, OpenCode, 그리고 사용자 인증이 완료된 Claude Code가 필요하다. Claude Code는 사용자 지정 MCP 채널을 지원해야 한다. 채널은 현재 연구 미리보기 단계다.
npm 배포판 패키지 이름은 @shivnathtathe/openbridge-mcp다. 전역 설치한 뒤 연결하려는 프로젝트에서 초기화한다.
npm install --global @shivnathtathe/openbridge-mcp
openbridge init
상태 파일은 설치 패키지 안이 아니라 작업 공간의 .openbridge/에 저장된다. OPENBRIDGE_PROJECT로 사용할 작업 공간을 지정할 수 있다. GitHub 소스 저장소를 비공개로 유지해도 설치한 모듈이 GitHub에서 애플리케이션 소스를 가져오지는 않는다. 다만 공개 npm 패키지에 포함된 실행 코드는 공개된다.
설치만으로 프로젝트 설정이 몰래 바뀌거나 세션이 실행되지는 않는다. 한 번 초기화하고 OpenCode를 다시 시작한 다음 ask_claude를 사용해 설정된 Claude 대상을 재사용하거나 실행한다. Claude가 열리면 필요한 로그인과 승인 요청을 완료해야 한다.
소스 체크아웃 방식으로 설치할 때는 소스 프로젝트 디렉터리에서 다음 명령을 실행한다.
npm install
npm run setup
설정 과정은 .openbridge/config.json을 만들고 opencode.json에 브리지를 병합한다. 기존 설정은 유지하고 첫 백업을 저장한다. 홈 디렉터리의 설정은 수정하지 않는다. OpenCode가 새 도구를 불러오도록 다시 시작해야 한다. 표준 JSON을 받으며 JSONC 파일을 다시 쓰지는 않는다.
소스 체크아웃에서 처음 Claude에 연결하려면 다음을 실행한다.
npm run claude
전역 npm 설치에서는 openbridge claude를 사용한다. 해당 터미널에서 로그인, 작업 공간 신뢰, MCP 동의, 개발 채널 확인을 완료해야 한다. 조직의 채널 정책도 이 기능을 허용해야 한다. 실행기는 Claude의 기본 --session-id UUID, 표시 이름, 모델, 생성된 MCP 설정과 사용자 지정 채널 활성화 플래그를 전달한다. 도구 권한을 우회하지는 않는다. 생성된 설정은 Claude 안에도 브리지 도구를 노출하므로 Claude가 OpenCode와 대화를 시작할 수 있다.
채널을 활성화하지 않고 임의로 연 Claude 창은 이 브리지에서 검색하거나 지정할 수 없다. 브리지 연결이 필요한 세션은 실행기를 사용해야 한다.
도구와 세션 정보
list_sessions()는 정확한 세션 ID, 표시 이름, 애플리케이션 제공자, 모델, 확인된 경우 모델 제공업체, 연결 상태, 메타데이터 출처를 반환한다.
{
"session_id": "ses_...",
"name": "API implementation",
"provider": "opencode",
"model_provider": "openai",
"model": "gpt-6.1-sol",
"status": "idle",
"reachable": true,
"metadata_source": "opencode_api"
}
Claude 세션 ID는 Claude의 --session-id 인수에 전달한 UUID다. 이름과 모델은 실행 시 설정값이며 이후 /rename, /model 또는 자동 대체 모델 변경을 실시간으로 관찰한 값은 아니다. 예를 들어 sonnet은 설정된 모델 별칭이지, 별도로 확인한 전체 모델 식별자가 아니다. model_provider는 관찰되지 않았으면 null이며 이름만으로 추측하지 않는다. 연결이 끊긴 설정된 Claude 대상도 offline 상태로 표시되며 요청에 따라 시작할 수 있다. 목록에는 이 프로젝트에 등록·설정된 Claude 세션만 나온다. Claude의 비공개 대화 기록 디렉터리를 검색하지 않는다.
channel_connected는 MCP 초기화가 완료되고 채널 하트비트가 살아 있다는 뜻이다. Claude가 채널 이벤트를 수락했다는 증거는 아니다. Claude 채널 프로토콜은 전달 확인 응답을 보내지 않는다. 연결에서 첫 응답을 성공적으로 받은 뒤에는 delivery_confirmed가 true가 된다.
ask_opencode와 ask_claude는 도구 이름으로 대상 어댑터를 선택한다. 세션 검색 결과의 대상 ID를 전달한다.
{
"session_id": "TARGET_NATIVE_SESSION_ID",
"message": "Please review these changes and explain any bugs.",
"provider": "opencode",
"model": "gpt-6.1-sol",
"source_session_id": "ses_SOURCE"
}
provider는 보내는 애플리케이션인 opencode 또는 claude를 뜻한다. model은 보내는 쪽의 모델이며 대상 모델을 덮어쓰는 설정이 아니다. source_session_id는 선택 항목이지만 알고 있다면 제공하는 편이 좋다. 실행기가 관리하는 Claude 채널은 출처 ID와 애플리케이션 정보를 직접 제공한다. OpenCode 출처 ID가 있으면 OpenCode API에서 모델과 제공업체를 조회한다. 그렇지 않으면 보낸 쪽 모델 정보는 호출자가 제공한 값으로 취급한다. 연결된 Claude의 출처 모델 정보는 실행 설정을 따른다.
수신자는 보낸 애플리케이션, 모델, 출처 세션, 정보 출처와 요청 ID를 명확히 표시한 협업 메시지 봉투를 받는다. 발신자 메타데이터는 출처를 나타낼 뿐 권한을 부여하거나 더 높은 우선순위의 지시가 되지 않는다.
결과에는 request_id, 요청 상태, 발신자 메타데이터, 확인 가능한 경우 수신자 메타데이터와 응답이 포함된다. 상태는 pending, completed, failed, unknown, released 중 하나다. MCP 전송 호출이 성공해도 상태를 확인해야 한다.
기존 클라이언트를 위해 OpenCode 전용 레거시 도구 ask_other도 남아 있다. 이 도구는 기존의 직접 HTTP 구현을 사용한다. 발신자 메타데이터, 관리형 시작, 요청 기록, 프로세스 간 조정이 필요하면 새 도구를 사용한다.
get_request(request_id)는 요청을 다시 보내지 않고 결과나 늦게 도착한 Claude 응답을 가져온다. 도구나 HTTP 시간 초과가 대상이 멈췄다는 증거는 아니다. 전달 여부가 확실하지 않은 프롬프트를 자동으로 재시도하지 않는다.
자동 시작과 연결 조건
MCP 클라이언트가 표준 입출력(stdio) 서버를 시작한다. 새 도구를 처음 사용할 때 서버는 인증된 로컬 루프백 브로커의 상태를 확인한다. 브로커가 없으면 프로젝트 시작 잠금을 사용해 중복 실행을 막고, 분리된 Node 프로세스로 브로커를 시작한다. 로그는 .openbridge/broker.log에 저장된다.
세션 검색과 OpenCode 요청은 /global/health를 확인한다. 서버에 연결할 수 없고 자동 시작이 설정되어 있으면 브로커가 백그라운드에서 opencode serve를 실행하고 준비 상태를 확인한다. 이미 정상인 서버가 있으면 재사용한다. ask_claude는 살아 있는 채널을 재사용하거나 선택된 설정 Claude 세션을 터미널에서 실행한다. 세션 검색만으로 Claude를 시작하지는 않는다.
Claude의 사용자 지정 채널 플래그에는 대화형 확인이 필요하다. 따라서 Claude를 시작하면 완전히 숨겨진 무인 실행이 아니라 터미널이 열린다. 연결된 뒤의 메시지 전송은 자동으로 이뤄진다. 제한된 시작 대기 시간 안에 동의가 끝나지 않으면 요청은 전달 전에 실패한다. 터미널에서 확인을 마친 뒤 다시 제출해야 한다.
터미널 자동 열기는 Windows의 PowerShell Start-Process와 Linux의 x-terminal-emulator에서 구현됐다. macOS에서는 터미널에서 openbridge claude를 실행해야 한다. Claude 실행 파일은 기본적으로 PATH의 claude를 사용한다. 세션의 선택 필드 command에 기본 실행 파일 경로를 지정할 수도 있다. 이 Claude 실행 파일 필드에서는 Windows 네이티브 npm .cmd shim을 지원하지 않는다.
OpenCode에 설정한 시작 명령은 설정 URL과 일치해야 한다. 기본 URL은 http://localhost:4096이며 기본 명령은 opencode serve --hostname 127.0.0.1 --port 4096이다. 자동 시작은 루프백 URL로 제한된다. 인증 실패나 예상하지 못한 HTTP·프로토콜 오류가 발생해도 서버를 다시 시작하지 않는다. 기존 서버가 기본 인증을 사용한다면 MCP 환경에서 OPENCODE_SERVER_PASSWORD와 선택 사항인 OPENCODE_SERVER_USERNAME을 설정한다. 자동 시작한 OpenCode 프로세스도 이 값을 상속한다. 자격 증명은 도구 출력에 포함되지 않는다.
MCP 클라이언트가 종료되어도 브로커는 계속 실행된다. .openbridge/config.json을 변경한 뒤에는 브로커를 다시 시작해야 한다. 기존 프로세스는 처음 읽은 설정을 계속 사용한다. 브리지는 기존 OpenCode나 Claude 프로세스를 자동으로 종료하지 않는다. 상태 확인에는 브로커 프로토콜 세대와 작업 공간 식별 정보가 포함된다. 호환되지 않는 구버전 프로세스는 재사용하지 않고 재시작이 필요하다는 오류를 낸다. 새 작업 공간은 초기화 시 사용 가능한 브로커 포트를 선택하며, 기존에 설정된 포트는 바꾸지 않는다. 선택한 포트가 나중에 다른 프로세스에 점유될 수 있으므로 포트 충돌이나 인증 문제를 해결해야 시작할 수 있다.
요청 안전성과 복구
공유 브로커는 MCP 클라이언트가 여러 개여도 대상 하나당 활성 요청을 하나로 제한한다. 확인 가능한 자기 호출과 순환 대기는 거부한다. 순환 감지는 제공된 출처 ID에 의존하며 이 브로커를 거치는 요청만 대상으로 한다. 모든 Claude 이벤트와 응답에는 요청 ID가 포함된다. Claude는 완료 시 final:true로 bridge_reply를 호출하고, 부분 응답은 final:false를 사용한다.
요청은 .openbridge/requests/에 기록된다. 브로커가 재시작되면 끝나지 않은 작업은 조용히 다시 전달하지 않고 unknown으로 표시한다. unknown 요청은 대상을 확인하고 명시적으로 해제할 때까지 대상 잠금을 유지한다. 기다린 시간이 길다는 이유만으로 해제해서는 안 된다.
openbridge release REQUEST_UUID --confirm-target-is-idle
Claude 채널 연결이 끊기거나 하트비트가 만료되면 진행 중인 작업의 전달 여부가 불확실해진다. 알림 쓰기에 성공했다고 모델이 처리했다는 뜻은 아니다. 브로커와 채널이 연결된 동안에는 늦게 도착한 Claude 응답을 가져올 수 있다. OpenCode HTTP 시간 초과 후에는 늦은 응답을 자동 복구하지 않는다. 재시도 여부를 정하기 전에 OpenCode의 기본 대화를 확인해야 한다.
요청 기록은 최대 500건으로 제한된다. 가득 차면 브로커를 중지하고 완료된 기록을 보관한 뒤 다시 시작한다. 요청 파일에는 메시지와 응답 내용이 들어 있으므로 비공개로 관리해야 한다. 로그나 콘텐츠를 자동으로 순환·정리하는 기능은 없다. 브로커 시작 잠금은 의도적으로 보수적으로 처리한다. 시작 중 충돌이 난 뒤 오래된 .openbridge/broker-start.lock을 지우려면 먼저 시작 작업이 진행 중이 아닌지 확인해야 한다.
Claude 실행기는 이후 --resume 사용을 결정하기 위해 실행 시도 기록을 남긴다. 첫 시도가 대화를 만들기 전에 실패했다면 다시 실행하기 전에 해당 세션의 .openbridge/claude-UUID.started 표시 파일을 제거한다.
브로커는 127.0.0.1에 바인딩하고 프로젝트별 무작위 토큰으로 각 요청을 인증한다. 브라우저 Origin 요청을 거부하고 입력과 응답 크기를 제한하며 사용자 메시지를 셸 명령에 넣지 않는다. .openbridge/는 Git 추적에서 제외된다. POSIX에서는 파일 소유자만 접근하도록 권한을 요청하며, Windows에서는 프로젝트 디렉터리의 ACL을 상속한다. 이 도구는 로컬 협업 기반 시설이지 같은 운영체제 사용자로 실행되는 다른 프로세스에 대한 격리 경계는 아니다.
명령과 프로젝트 구성
openbridge init
openbridge sessions
openbridge doctor
openbridge claude
openbridge claude --session UUID --window
openbridge release REQUEST_UUID --confirm-target-is-idle
소스 체크아웃에서는 openbridge 대신 node src/cli/index.js를 실행하거나 이에 해당하는 npm 스크립트를 사용한다. npm test는 개발 테스트 모음을 실행한다. npm run export:history는 특정 프로젝트의 개발 보조 도구이며 npm 패키지에는 포함되지 않는다.
세션 설정은 기본 Claude 검토자 UUID를 포함해 로컬에서 생성된다. 비공개 설정의 claude_sessions에 고유한 네이티브 UUID, name, model, auto_start 설정을 가진 객체를 추가한 뒤 브로커를 다시 시작하면 세션을 늘릴 수 있다. 네임스페이스가 붙은 대상 식별자는 향후 작업 항목이다. 현재는 ask_claude 또는 ask_opencode 도구를 고른 뒤 네이티브 ID를 전달해야 한다.
저장소 구성은 다음과 같다. src/adapters/에는 OpenCode HTTP 어댑터, src/broker/에는 HTTP 경로·서비스 수명 주기·요청 조정·기록 기능, src/claude/에는 네이티브 MCP 채널과 생성된 채널 설정이 있다. src/cli/는 설치된 openbridge 명령을, src/core/는 작업 공간 런타임·진입점 경로·공유 검증을, src/mcp/는 MCP 서버와 공유 도구 등록을 담당한다. 이 항목은 모두 npm 패키지에 포함된다.
assets/에는 원본 밝은 테마 로고와 어두운 테마용 흰색 로고 두 가지가 있다. tests/의 어댑터·브로커·실제 npm 설치 스모크 테스트, scripts/의 개발 유틸리티, docs/의 아키텍처 및 개발 기록, .openbridge/의 로컬 설정·자격 증명·로그·요청 상태, hisotry_conco/의 보존된 로컬 대화 보관 자료는 npm 패키지에 포함되지 않는다.
아키텍처, 개발 노트와 개발 과정 기록은 비공개 소스 저장소의 docs/에 있으며 저장소 접근 권한이 있어야 볼 수 있다. 이 소스 전용 문서는 실행용 npm 압축 파일에서 제외된다. 설치 및 운영 안내는 npm 패키지에 포함된다.
기존 레이아웃에서 업그레이드
업데이트를 설치한 뒤 초기화를 다시 실행한다. 기존 토큰과 설정된 세션 ID는 유지하고, 관리 대상 Claude MCP 파일 경로를 새로 고치며, OpenCode 진입점을 원자적으로 업데이트한다. 원래 클라이언트 설정의 백업은 이제 소스 파일 옆이 아니라 .openbridge/ 안에 저장된다.
새 레이아웃을 사용하기 전에 기존 브리지 연결 Claude 터미널을 닫고 프로젝트 브로커와 OpenCode를 다시 시작한다. 이미 실행 중인 구버전 코드는 이동한 모듈이나 생성된 설정을 자동으로 다시 읽지 않는다. 초기화는 진행 중인 대화를 강제로 종료하지 않는다.
검증과 현재 한계
테스트는 실제 MCP 표준 입출력 클라이언트, 공유 HTTP 브로커, 제어된 OpenCode 모의 엔드포인트를 대상으로 한 실제 채널 프로세스를 다룬다. 메타데이터, 양방향 통신, 응답 일치, 시간 초과와 늦은 응답, 중복 요청, 순환 대기, 인증, 충돌 복구를 포함한다. 단위·통합 테스트만으로 모든 플랫폼에서 Claude 미리보기 기능이 동일하게 동작한다고 입증할 수는 없다.
패키지 스모크 테스트는 압축 파일을 만들고 경로에 공백이 있는 별도 프로젝트에 설치한 뒤 설치된 명령을 실행한다. 또한 사용자 설정을 유지하면서 관리 경로가 마이그레이션되는지 확인한다. 테스트 의존성을 설치할 때 npm 레지스트리가 필요할 수 있다. 이 스모크 테스트는 모델 서비스를 시작하지 않는다.
Windows 실사용 테스트도 성공적으로 완료됐다. OpenCode가 ask_claude를 통해 메시지를 보내고 Claude가 네이티브 채널로 응답했으며, 응답에는 발신 애플리케이션과 모델이 올바르게 반복됐다. Claude는 응답에서 자기 모델을 식별했고 브로커는 설정된 sonnet 별칭을 별도로 유지했다.
프로젝트는 보안 강화를 거친 작동 구현이지만, 프로덕션 인증을 받았다는 주장은 아니다. 남은 작업에는 실시간 Claude 신원·제목 업데이트, 더 폭넓은 플랫폼 테스트, 자동 요청 기록 보존, 명시적 데몬 관리, 상위 인터페이스가 허용하는 범위에서 더 강한 종단 간 전달 확인이 포함된다.
프로토콜 참조 자료:
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요