Restura 데스크톱 MCP 제어 서버로, Claude Code와 Codex가 API 클라이언트를 구동할 수 있게 해줍니다

What they did

저자는 API 클라이언트 데스크톱 앱인 Restura에 MCP 제어 서버를 추가했다. 이를 통해 Claude Code, Codex, Claude Desktop 같은 에이전트가 앱에서 사용자가 하는 일을 그대로 수행할 수 있다. 컬렉션, 폴더, 요청(HTTP, GraphQL, gRPC, SSE, MCP)을 탐색하고 만들기, 환경 관리, OpenAPI, Postman, Insomnia, OpenCollection, curl 가져오기, 요청 전송, 컬렉션 실행 등이다. Electron 메인 프로세스가 127.0.0.1에서 스트리머블 HTTP MCP 서버를 호스팅하며, 각 도구 호출은 IPC를 통해 서버를 활성화한 윈도우로 전달되고, 해당 윈도우는 UI와 동일한 스토어 액션을 통해 이를 실행한다. 따라서 전송은 컬렉션 러너(SSRF 가드, 인증 서명, 스크립트)를 거친다. `Restura --mcp-server` 플래그는 0600 핸드셰이크 파일에서 포트와 토큰을 읽는 stdio 릴레이가 되어, 에이전트 설정에 비밀이 노출되지 않게 한다. 26개 도구의 단일 공유 카탈로그가 HTTP 서버, 릴레이, 렌더러에 서비스를 제공한다. 컬렉션별 접근 수준(hidden/read/edit/full)과 환경별 접근 수준(hidden/read/edit에 더해 별도의 전송 플래그)은 모두 hidden으로 시작하며 서버는 꺼진 상태다. 편집은 자동 승인되지 않는 한 확인을 요청하고, 삭제, 전송, 모든 스크립트 변경은 항상 확인을 요청하며 전체 스크립트를 보여준다. 대화상자가 열려 있는 동안 대상이 변경되면 승인이 무효화된다. 모든 변경은 에이전트 이름과 함께 기록되며, 이후 무언가 변경되었다면 실행 취소는 거부된다. 비밀은 읽을 때 마스킹되고, 자격 증명 쓰기는 `{{variable}}`만 허용하며, 마스킹된 값을 그대로 복사해 되돌려 쓰면 실제 값이 보존된다. 전송은 시작할 때마다 새로 생성되는 256비트 베어러 토큰을 사용하고, Origin/Sec-Fetch 헤더를 거부하며, 루프백 Host를 요구하고, 속도 제한을 적용하며, 최대 40 MiB까지 허용한다. Settings → MCP Server 페이지에는 스위치, 접근 설정, Claude Code, Codex, Claude Desktop용 복사-붙여넣기 설정, 활동 로그가 있다. 설계는 ADR 0041에 있으며 ADR 0011의 헤드리스 서버를 대체하고, 리포지토리의 코드 리뷰 스킬을 Deep 깊이로 세 차례 검토했다.

How it went

`mcp.serverMode`와 함께 재생성된 capability matrix에 데스크톱 전용 기능으로 출시되었습니다. Type-check, lint ratchet, biome, architecture 및 capability 검사가 통과했고, 전체 단위 테스트 스위트는 12,642개의 테스트가 통과했으며, 마지막 수정 이후 MCP, shared, security 스위트에서 190개가 통과했습니다. HTTP 서버 테스트는 실제 MCP SDK 클라이언트를 사용해 토큰, Origin/Host 검사, rate limit 및 40 MiB 요청을 검증했습니다. 보안 테스트를 통해 어떤 read 도구도 심어둔 15개의 secret을 유출하지 않음, 마스킹된 값이 secret을 절대 덮어쓰지 않음, 어떤 도구 모듈도 자체 접근 권한을 변경할 수 없음, 인자에 포함된 평문 자격 증명이 거부됨을 확인했습니다. 데스크톱 e2e 스펙은 앱을 시작하고 실제 stdio relay를 통해 연결하여 read, approval, edit 및 send 흐름을 구동했습니다. 전체 e2e 실행은 69개 통과, 7개 스킵으로 통과했으며, 그중 2개는 broker가 필요한 Kafka 스펙입니다. 코드 리뷰 1라운드에서 21개의 이슈가 발견되었고, 2라운드에서는 3개의 blocker와 4개의 미확인 항목이 발견되었으며 모두 수정되었습니다. 3라운드에서는 차단 요소가 발견되지 않았고, 두 가지 사소한 지적 사항은 수정되거나 문서화되었습니다.

Worth knowing

데스크톱 전용: 웹, 셀프 호스팅, CLI 하네스에는 서버를 호스팅할 로컬 프로세스가 없습니다. 지연된 작업에는 WebSocket, Socket.IO, Kafka, MQTT용 프리셋, HAR 가져오기/내보내기, 워크플로가 포함되며, `mcp-server-next`로 추적됩니다. 이 글에는 실제 도구 스키마, 핸드셰이크 파일 형식, 또는 모든 항목이 숨김으로 시작하고 서버가 꺼진 상태로 시작한다는 것 이상의 정확한 설정 기본값은 포함되어 있지 않습니다. 두 개의 e2e 스킵은 브로커가 필요한 main의 Kafka 스펙이므로, 해당 경로는 여기서 실행되지 않았습니다.

Wiring

Electron 메인 프로세스는 127.0.0.1에 바인딩된 streamable-HTTP MCP 서버를 시작하며, 256비트 베어러 토큰은 시작할 때마다 재생성됩니다. 서버는 포트와 토큰을 담은 0600 핸드셰이크 파일을 작성하고, `Restura --mcp-server`가 이를 읽어 stdio 릴레이로 동작하므로 에이전트 설정 파일에 비밀이 저장되지 않습니다. HTTP 서버에 도착한 도구 호출은 Electron IPC를 통해 서버를 활성화한 렌더러 창으로 전달되며, 렌더러는 UI와 동일한 store 액션을 통해 이를 실행합니다. 전송은 컬렉션 러너(SSRF 가드, 인증 서명, 스크립트)를 거칩니다. shared/mcp-server/control-tools.ts에 있는 단일 카탈로그(26개 도구)는 HTTP 서버, stdio 릴레이, 렌더러에서 임포트됩니다. 접근 수준과 on/off 스위치는 Settings → MCP Server에 있으며 서버 측에서 강제됩니다. 승인, 활동 로그, 실행 취소는 store 액션을 감쌉니다. 전송 가드는 Origin, Sec-Fetch-Site 또는 Sec-Fetch-Dest 헤더가 있는 요청을 거부하고, 루프백 Host를 요구하며, 속도 제한을 적용하고 최대 40 MiB의 본문을 허용합니다. 기능 매트릭스 항목 `mcp.serverMode`는 이 기능을 데스크톱 전용으로 표시합니다.

Try it yourself

I'll start by reading the ADR and exploration spec to understand the requirements.

<｜｜DSML｜｜ calls>
<｜｜DSML｜｜ invoke name="bash">
<｜｜DSML｜｜ parameter name="command" string="true">cat docs/adr/0041-mcp-control-server.md 2>/dev/null | head -300</｜｜DSML｜｜ parameter>
</｜｜DSML｜｜ invoke>
</｜｜DSML｜｜ calls>