Toolport: AI 클라이언트와 MCP 서버 사이의 로컬 게이트웨이 프로젝트

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

Toolport는 AI 클라이언트들과 MCP 서버 사이에 위치하는 로컬 게이트웨이로, 전체 툴 카탈로그를 컨텍스트에 주입하지 않고 네 개의 작은 메타툴을 통해 모델이 필요한 툴만 검색하게 하는 lazy discovery로 토큰 오버헤드를 크게 줄였다. 저자는 측정된 최소 토큰 사용량을 886토큰으로 제시했으며 승인 큐를 통해 에이전트의 위험한 툴 호출을 인간 승인 전까지 차단하는 안전 제어를 도입했다. 구현은 Tauri 2와 React 19 기반의 데스크톱 앱과 별도 Rust 게이트웨이 바이너리(사이드카)로 이루어졌고, Windows MSIX 가상화 같은 플랫폼 이슈는 전용 프로브로 검증해 해결했다. 모든 변경을 PR로 관리하고 적대적 감사를 반복해 CSV 인젝션·SSRF·CI 미실행 테스트 같은 취약점을 찾아낸 점이 코드 품질을 높이는 핵심 실천이었다.

실용적 조언

혼자 개발하더라도 변경은 모두 PR로 관리하면 각 변경의 의도를 검색하고 나중에 이유를 추적하기가 쉬워진다.
적대적 감사 방식을 도입해 에이전트를 코드를 대상으로 버그 찾기 임무에 투입하고, 발견을 두 번째 검증자(또는 에이전트)가 반박하지 못할 때만 신뢰하는 방식이 미묘한 취약점을 잡는 데 효과적이었다.
스쿼시 머지를 사용할 때 브랜치 커밋 메시지에 [skip ci] 같은 자동화 제어 문자열이 섞이지 않도록 주의해야 하며, 이를 방지하려면 병합 전 커밋 메시지를 검토하거나 CI 정책을 분리하는 방법을 고려해야 한다.

섹션별 상세

툴 스키마를 모두 컨텍스트에 넣으면 토큰 비용이 크게 증가하는 문제를 해결하기 위해 Toolport는 클라이언트와 서버 사이에 로컬 게이트웨이를 배치했다. 게이트웨이는 네 개의 작은 메타 툴만을 노출하고 모델이 필요한 툴을 직접 검색하도록 구성되어 입력 토큰을 최소화한다. 저자가 측정한 최소 토큰 사용량은 886토큰이며, 전체 툴 카탈로그를 직접 주입했다면 수만 토큰이 소모될 수 있다고 명시되어 있다. 이 접근은 여러 AI 클라이언트가 하나의 로컬 엔드포인트를 공유하면서도 컨텍스트 오버헤드를 줄이는 실무적 이점을 제공한다.

자동화 에이전트가 임의로 위험한 툴 호출을 실행하는 위험을 통제하기 위해 승인 큐가 도입되었다. 승인 큐는 에이전트가 호출을 요청하면 사용자가 직접 클릭으로 승인할 때까지 실제 실행을 보류하는 방식으로 동작하며, 이 과정에서 호출 요청의 메타데이터가 인간 검토 대상으로 남는다. 게시자는 이 메커니즘 때문에 에이전트가 위험한 작업을 자동으로 수행하지 못하게 막을 수 있었다고 적었다. 승인 큐는 인간-중심의 안전 제어 지점을 제공함으로써 외부 사이드 이펙트가 있는 작업을 보다 안전하게 다루게 한다.

구현 스택은 Tauri 2·React 19 기반의 데스크톱 앱과 별도의 Rust 게이트웨이 바이너리(사이드카)로 구성되며, 프로젝트 초기 커밋과 현재 커밋 수(첫 커밋은 6월 19일, 현재 474커밋)가 명시되어 있다. Windows Store 패키징 환경에서는 MSIX 가상화가 일부 파일 쓰기를 섀도 위치로 리다이렉트해 동일 경로에서 서로 다른 프로세스가 다른 설정을 읽는 문제가 발생했고, 이를 증명하기 위해 목적에 맞춘 프로브 스크립트를 작성해 원인을 확인했다. 이러한 플랫폼별 배포와 가상화 이슈는 데스크톱 앱과 사이드카 아키텍처를 운영할 때 추가적인 검증과 탐지 수단이 필요하다는 실무적 교훈을 남긴다.

개발 워크플로우는 단독 개발자임에도 모든 변경을 PR로 처리하는 규칙과 정기적인 적대적 감사를 핵심으로 삼았다. 적대적 감사는 새로운 Claude 세션을 전체 코드베이스에 포인팅해 실제 버그를 찾게 한 뒤, 각 발견 사항이 두번째 에이전트의 반박을 견뎌야 신뢰할 만하다고 판단하는 이중 검증 절차로 구성되어 있다. 이 과정에서 CSV 인젝션, 서버 측 요청 위조(SSRF) 취약점, 그리고 CI에서 특정 Rust 테스트 그룹이 실제로 실행되지 않아 몇 주간 실패가 은폐된 사례가 발견되었다. 이러한 반복적 자동화 감사와 PR 중심 기록 관리는 장기적으로 코드 품질과 추적 가능성을 높였다는 실무적 증거를 제공한다.

용어 해설

툴 스키마(Tool Schema): — 툴 스키마는 외부 툴의 기능과 입력·출력 형식을 기계가 이해하도록 구조화한 메타데이터이다. 툴 스키마는 모델이 어떤 파라미터를 보내야 하는지와 예상되는 응답 포맷을 명시하며, 이를 통해 자동화된 호출과 재현 가능한 통합이 가능해진다. 대규모 툴 카탈로그를 그대로 컨텍스트에 포함하면 토큰 비용과 처리 지연이 크게 증가하기 때문에, 스키마를 어떻게 노출하느냐가 시스템 효율성에 직접적인 영향을 준다.
레이지 디스커버리(Lazy Discovery): — 레이지 디스커버리는 모든 툴 정보를 한 번에 주입하지 않고 모델의 필요가 생겼을 때 최소한의 메타툴이나 검색으로 관련 툴을 동적으로 노출하는 방식이다. 이 방식은 컨텍스트 윈도우에 들어가는 토큰을 크게 줄이며, 모델이 실제로 요청하는 기능만 탐색하게 만든다. Toolport에서는 4개의 작은 메타툴을 노출해 모델이 필요한 툴을 검색하게 하는 방식으로 토큰 사용량을 크게 낮췄다.
승인 큐(Approval Queue): — 승인 큐는 에이전트가 툴 호출을 요청했을 때 사람이 직접 승인해야 실제 호출이 발생하도록 하는 인터셉터 메커니즘이다. 이 메커니즘은 위험한 자동 실행을 차단하고 사람 중심의 확인 절차를 보장하며, 특히 외부 액션(파일 쓰기·네트워크 호출 등)에 대해 보호 계층을 제공한다. Toolport는 승인 큐를 통해 에이전트의 임의 호출을 차단하고 사용자가 수동으로 승인한 경우에만 실행되게 구성된다.
사이드카(Sidecar): — 사이드카는 주요 애플리케이션과 같은 호스트에서 별도의 프로세스로 동작하는 보조 바이너리로, 주 애플리케이션과 통신해 특정 기능을 분리해서 제공한다. 네트워크 게이트웨이·로깅·프록시처럼 독립 실행형으로 관리해야 할 컴포넌트를 사이드카로 배치하면 배포 유연성과 언어 독립성이 확보된다. Toolport는 Tauri 기반 데스크톱 앱과 별개의 Rust 게이트웨이 바이너리를 사이드카로 배포했다.
MSIX 가상화(MSIX Virtualization): — MSIX 가상화는 Windows Store 방식의 패키징에서 일부 파일 쓰기를 샌드박스화하여 원래 경로 대신 가상화된 섀도 디렉터리에 기록하도록 리다이렉션하는 동작이다. 이로 인해 동일한 파일 경로를 사용하더라도 서로 다른 프로세스가 다른 물리적 파일을 보게 되어 구성 일관성이 깨질 수 있다. Toolport의 사례에서는 데스크톱 앱과 스폰된 게이트웨이가 같은 경로에서 서로 다른 설정을 읽는 현상이 MSIX 가상화 때문에 발생했다.

언급된 도구

Tauri 2중립

데스크톱 앱 셸로 사용되어 브라우저 기반 UI와 네이티브 바이너리를 연결하는 역할을 수행한다.

React 19중립

데스크톱 앱의 프론트엔드 UI를 구성하는 라이브러리로서 사용자 인터페이스 상태와 렌더링을 담당한다.

Rust gateway (sidecar)중립

AI 클라이언트와 MCP 서버 사이의 로컬 게이트웨이 로직을 별도 바이너리로 실행해 네트워크/툴 호출을 중계하고 안전 제어를 수행한다.

Claude Desktop중립

AI 클라이언트 사례로 언급되어 게이트웨이와 통신하는 데 사용된 데스크톱 기반 모델 인터페이스를 대표한다.

언급된 리소스

GitHubToolport GitHub

DemoToolport.app