Restura desktop MCP control server letting Claude Code and Codex drive an API client

What they did

The author added an MCP control server to Restura, an API client desktop app, so agents like Claude Code, Codex and Claude Desktop can do what a user does in the app: browse and build collections, folders and requests (HTTP, GraphQL, gRPC, SSE, MCP), manage environments, import OpenAPI, Postman, Insomnia, OpenCollection and curl, send requests and run collections. The Electron main process hosts a streamable-HTTP MCP server on 127.0.0.1; each tool call goes over IPC to the window that enabled the server, which runs it through the same store actions as the UI, so sends pass through the collection runner (SSRF guard, auth signing, scripts). A `Restura --mcp-server` flag becomes a stdio relay that reads port and token from a 0600 handshake file, keeping secrets out of agent config. One shared catalogue of 26 tools serves the HTTP server, relay and renderer. Access levels per collection (hidden/read/edit/full) and per environment (hidden/read/edit plus a separate send flag) all start hidden with the server off. Edits ask unless auto-approved; deletes, sends and any script change always ask and show the full script. Approvals are invalidated if the target changes while the dialog is open. Every change is logged with the agent name and undo refuses if anything changed after. Secrets are masked on read, credential writes accept only `{{variable}}`, and masked values copied back unchanged preserve the real value. Transport uses a fresh 256-bit bearer token per start, refuses Origin/Sec-Fetch headers, requires loopback Host, rate limits, and accepts up to 40 MiB. A Settings → MCP Server page holds the switch, access settings, copy-paste setup for Claude Code, Codex and Claude Desktop, and the activity log. The design is in ADR 0041, replacing ADR 0011's headless server, and was reviewed in three rounds of the repo's code-review skill at Deep depth.

How it went

Shipped as a desktop-only feature with `mcp.serverMode` in the regenerated capability matrix. Type-check, lint ratchet, biome, architecture and capability checks pass; the full unit suite ran 12,642 passing tests, with 190 in the MCP, shared and security suites after the last fix. An HTTP server test used the real MCP SDK client to verify token, Origin/Host checks, rate limit and 40 MiB requests. Security tests confirmed no read tool leaks any of 15 planted secrets, masked values never overwrite secrets, no tool module can change its own access, and plaintext credentials in arguments are rejected. A desktop e2e spec started the app, connected through the real stdio relay and drove read, approval, edit and send flows; the full e2e run passed 69 with 7 skipped, 2 of them Kafka specs needing a broker. Code review round 1 found 21 issues, round 2 found 3 blockers plus 4 unconfirmed items, all fixed; round 3 found nothing blocking and its two minor points were fixed or documented.

Worth knowing

Desktop-only: web, self-hosted and CLI harnesses have no local process to host the server. Deferred work includes presets for WebSocket, Socket.IO, Kafka and MQTT, HAR import/export and workflows, tracked as `mcp-server-next`. The post does not include the actual tool schemas, the handshake file format, or the exact settings defaults beyond everything starting hidden and the server starting off. Two e2e skips are Kafka specs from main that need a broker, so those paths were not exercised here.

Wiring

Electron main process starts a streamable-HTTP MCP server bound to 127.0.0.1 with a 256-bit bearer token regenerated each start. The server writes a 0600 handshake file containing port and token; `Restura --mcp-server` reads it and acts as a stdio relay so agent config files never hold the secret. Tool calls arriving at the HTTP server are forwarded over Electron IPC to the renderer window that enabled the server, which executes them via the same store actions as the UI; sends route through the collection runner (SSRF guard, auth signing, scripts). A single catalogue at shared/mcp-server/control-tools.ts (26 tools) is imported by the HTTP server, the stdio relay and the renderer. Access levels and the on/off switch live in Settings → MCP Server and are enforced server-side; approvals, activity log and undo wrap the store actions. Transport guards reject requests with Origin, Sec-Fetch-Site or Sec-Fetch-Dest headers, require a loopback Host, apply rate limits and accept bodies up to 40 MiB. Capability matrix entry `mcp.serverMode` marks the feature desktop-only.

Try it yourself

Read docs/adr/0041-mcp-control-server.md and the exploration spec in docs/superpowers/specs/2026-11-03-mcp-control-server-exploration.md in this repo. Then implement the MCP control server as described: host a streamable-HTTP MCP server on 127.0.0.1 from the Electron main process, forward each tool call over IPC to the window that enabled it, and run tools through the same store actions the UI uses so sends go through the collection runner. Add a `--mcp-server` stdio relay that reads port and token from a 0600 handshake file. Put the 26-tool catalogue in shared/mcp-server/control-tools.ts so the HTTP server, relay and renderer share it. Implement per-collection access levels (hidden/read/edit/full) and per-environment levels plus a separate send flag, all defaulting to hidden with the server off. Add approvals that always fire for deletes, sends and script changes, invalidate when the target changes mid-dialog, log every change with the agent name, and refuse undo if anything changed after. Mask secrets on read, accept only `{{variable}}` for credential writes, preserve real values when masked values are copied back, and label third-party content as untrusted. Enforce a fresh 256-bit bearer token per start, reject Origin/Sec-Fetch headers, require loopback Host, rate limit, and allow 40 MiB requests. Build the Settings → MCP Server page with the switch, access settings, copy-paste setup for Claude Code, Codex and Claude Desktop, and the activity log. Add unit tests for the catalogue, access levels, redaction, IPC bridge, relay and masked-value restore, an HTTP test with the real MCP SDK client, tests/security/mcp-control-server.test.ts with planted secrets, and an e2e spec that drives read, approval, edit and send through the real relay.