Ide Relay Mcp

Relay

The missing human checkpoint for AI coding agents.

Give your AI agent a "pause & ask" button — review, correct, or enrich every step before it runs.

Download · [简体中文](READMEzh.md)

Author: andeya · [andeyalee@outlook.com](mailto:andeyalee@outlook.com)

Relay beside your IDE — the agent pauses, you review & answer, it continues. All in one tools/call.

---

Why Relay?

AI coding agents are powerful — but blindly autonomous agents are risky and wasteful. Without a checkpoint, agents go on tangents, make mistakes that cascade into multiple correction rounds, and burn through your precious plan quota on wasted requests.

Relay adds a human-in-the-loop (HITL) checkpoint to any MCP-capable agent. The agent calls one tool — relay_interactive_feedback — and blocks until you submit your Answer (text, images, files). The result returns on the same JSON-RPC round trip. You catch issues early, guide accurately, and make every request count — no cloud dashboards, no extra SaaS, just a native desktop window beside your IDE.

Key advantages

| | | | -------------------------- | ------------------------------------------------------------------------------------------------------------- | | Works with any MCP IDE | First-class support for Cursor, Claude Code, Windsurf, and a generic mode for others. | | 100% local | All data stays on your machine — loopback HTTP only, zero telemetry, no phone-home. | | One resident GUI | A single persistent window (not a popup per request) with multi-tab session management. | | No ARG_MAX limits | retell travels as HTTP JSON body (up to 16 MiB), not shell argv. | | Session continuity | relay_mcp_session_id links turns into coherent sessions with MM-DD HH:mm:ss tab labels. | | Rich feedback | Text, screenshots, file attachments — everything the agent needs in one round trip. | | Save your plan quota | Catch mistakes early and guide precisely — no more wasted correction rounds burning through premium requests. |

---

Multi-IDE support

Launch Relay and pick your IDE. Each mode unlocks IDE-specific features — one-click MCP injection, tailored rule prompts, and (for Cursor) real-time usage monitoring.

Click a card to enter that IDE mode — all settings, CLI commands, and MCP config adapt automatically.

| IDE | MCP injection | Rule prompts | Usage monitoring | | --------------- | :-----------: | :----------: | :--------------: | | Cursor | ✅ | ✅ | ✅ | | Claude Code | ✅ | ✅ | — | | Windsurf | ✅ | — | — | | Other | manual | — | — |

---

Quick start

1. Install — Grab the latest release (macOS, Linux, Windows) or [build from source](#build).

macOS — Gatekeeper / quarantine: CI-built .app bundles are not Apple-notarized (that requires a paid Developer ID certificate). Downloads from the browser get the com.apple.quarantine attribute, which can trigger “can’t be opened” or “damaged” warnings. Without a paid cert there is no fully automatic fix for all users; options are:

• Recommended: In Finder, Control-click (or right-click) the app → Open and confirm once (stores an exception for that app).
• CLI (one-time): clear quarantine after copying the app to Applications (adjust the path if yours differs):

xattr -dr com.apple.quarantine "/Applications/Relay.app"

2. Launch & choose IDE — Run relay and click your IDE card, or go directly:

relay gui-cursor        # Cursor mode
relay gui-claudecode    # Claude Code mode
relay gui-windsurf      # Windsurf mode

3. Wire MCP — Point your IDE at the Relay binary. Example for Cursor:

{
  "mcpServers": {
    "relay-mcp": {
      "command": "/path/to/relay",
      "args": ["mcp-cursor"],
      "autoApprove": ["relay_interactive_feedback"]
    }
  }
}

> Cursor uses .cursor/mcp.json (per-repo, merged with ~/.cursor/mcp.json). > For WSL agent + Windows relay.exe, add --exe_in_wsl: ["mcp-cursor", "--exe_in_wsl"]. > See [docs/HTTPIPC.md](docs/HTTPIPC.md) for details.

Or use Settings → Environment & MCP inside Relay for one-click setup and to copy the MCP JSON directly:

Settings → Environment & MCP — PATH detection, one-click MCP injection, copy JSON, pause MCP.

4. Install rule prompts — Go to Settings → Rule prompts and install with one click. This teaches the agent to call relay_interactive_feedback every turn and maintain relay_mcp_session_id.

Settings → Rule prompts — one-click install into your IDE's rule configuration.

Cursor rule file — One-click install writes relay-interactive-feedback.mdc under user ~/.cursor/rules/ (Windows: %USERPROFILE%\.cursor\rules\). That path is separate from a repo’s .cursor/rules/; copy or symlink there if you only use project rules.

Agent still skips relay_interactive_feedback? Ensure MCP server relay-mcp is enabled; approve the tool when prompted (or set "autoApprove": ["relay_interactive_feedback"]); reload Cursor after editing the rule file on disk. Rule files guide the model — they are not hard guarantees.

---

Relay human-in-the-loop (end-to-end)

After Quick start steps 2–4, each turn follows this path (transport detail: [docs/HTTPIPC.md](docs/HTTPIPC.md); vocabulary: [docs/TERMINOLOGY.md](docs/TERMINOLOGY.md)):

sequenceDiagram
  participant Agent
  participant Mcp as relay_mcp-ide
  participant Http as GUI_HTTP_127.0.0.1
  participant You

  Agent->>Mcp: tools/call relay_interactive_feedback (retell, session, commands/skills…)
  Mcp->>Http: POST /v1/feedback → request_id
  Http->>You: tab shows retell
  You->>Http: Answer / dismiss / idle cutoff
  Http-->>Mcp: GET …/wait → JSON result
  Mcp-->>Agent: same tools/call response

1. MCP runs — The IDE launches relay mcp- (stdio), e.g. mcp-cursor. The matching GUI is relay gui- (often already open).
2. Agent calls the tool — Non-empty retell. New session: omit relay_mcp_session_id (or empty) and send commands and skills (each may be [] only if the host truly exposes nothing). Continue: pass the relay_mcp_session_id from the previous result.
3. MCP reaches the GUI — Reads gui_endpoint_.json in your [Configuration & paths](#configuration--paths) directory (e.g. gui_endpoint_cursor.json), or spawns relay gui- and waits ≤ ~45 s. Then POST /v1/feedback and blocks on GET /v1/feedback/wait/:id until the tab completes.
4. You interact — Submit Answer, attach files, dismiss, or let the ~60 min idle cleanup return empty human (same as dismiss from the agent’s perspective).
5. Same JSON-RPC returns — Body includes relay_mcp_session_id, human, cmd_skill_count, optional attachments. The next turn must send that relay_mcp_session_id unless starting a new tab.

Rules vs MCP: Step 4’s rule prompt install writes relay-interactive-feedback.mdc under user ~/.cursor/rules/ (Cursor only). Rules encourage the loop; relay-mcp in MCP settings executes it.

---

Architecture

flowchart LR
  IDE[IDE / Agent] -->|stdio JSON-RPC| MCP["relay mcp-{ide}"]
  MCP -->|read or spawn| GUI["relay gui-{ide}"]
  MCP |127.0.0.1 Bearer| HTTP[Tauri HTTP API]
  HTTP  UI[Vue tabs]
  UI --- User((You))
  MCP -->|JSON result| IDE

• relay mcp-{ide} — Stdio MCP server (clap). Handles initialize, tools/list, tools/call. Concurrent human rounds on one connection. Optional auto-reply rules.
• relay / relay gui- — Tauri app + HTTP on 127.0.0.1:0. Writes gui_endpoint_.json (e.g. gui_endpoint_cursor.json) with { port, token, pid }; cleans up on exit.
• Bridge — MCP reads the endpoint file; if missing, spawns gui-{ide} and polls up to ~45 s. Then POST /v1/feedback → GET /v1/feedback/wait/:id. The wait resolves on submit, dismiss, supersede, or ~60 min idle.

---

MCP tool: relay_interactive_feedback

| Argument | Required | Meaning | | -------------------------- | --------------------- | --------------------------------------------------------------------------------- | | retell | yes (non-empty) | This turn's user-visible assistant reply, verbatim. | | relay_mcp_session_id | if you have one | Continue the same session; returned in the JSON result. | | commands | new tab: required | Array of IDE commands for slash-completion. [] only if the host truly has none. | | skills | same as commands | Array of IDE skills. Same merge/dedupe rules. |

Pause MCP (Settings): sentinel >> — do not call again until resumed.

Slash completion — commands and skills populate the palette with optional category badges.

---

Features at a glance

• Multi-tab hub — Each request opens or refreshes a tab. relay_mcp_session_id merges streams. Labels show MM-DD HH:mm:ss with turn-status color indicators.
• Rich composer — Enter to submit, Shift+Enter for newline, ⌘/Ctrl+Enter to submit & close. Paste images, attach files — they appear as attachments in the tool result.
• Cursor Usage monitoring — Auto-detect your Cursor token (cross-platform decryption), view plan quotas, request history, and predicted quota exhaustion in a live popover.
• Auto-reply — auto_reply_oneshot.txt / auto_reply_loop.txt for instant 0|reply responses without opening the UI.
• Local storage — feedback_log.txt, qa_archive/.jsonl, configurable attachment retention (default 30 days).
• CLI — relay feedback --retell "…" prints JSON on stdout; --timeout for CI/automation.

Settings → Cache — attachment + log usage, open folder, auto-clean.

---

CLI reference

| Command | Role | | ----------------------------- | ------------------------------------------------------ | | relay | Open IDE selection page | | relay gui-cursor | Launch GUI in Cursor mode | | relay gui-claudecode | Launch GUI in Claude Code mode | | relay gui-windsurf | Launch GUI in Windsurf mode | | relay mcp-cursor | MCP stdio server for Cursor (what the IDE runs) | | relay mcp-claudecode | MCP stdio server for Claude Code | | relay mcp-windsurf | MCP stdio server for Windsurf | | relay feedback --retell "…" | Terminal tryout; --timeout, --relay-mcp-session-id |

Only one GUI process per IDE mode is allowed; bare relay (no mode) can run multiple instances.

---

Configuration & paths

Data lives under your OS application-data directory (directories::ProjectDirs → config_dir()):

| OS | Path | | ------- | ---------------------------------------------------- | | macOS | ~/Library/Application Support/com.relay.relay-mcp/ | | Linux | ~/.config/relay-mcp/ | | Windows | %APPDATA%\relay\relay-mcp\config\ |

Key files: feedback_log.txt, qa_archive/*.jsonl, ui_locale.json, gui_endpoint_.json (e.g. gui_endpoint_cursor.json), relay_gui__alive.marker, mcp_pause.json, attachment_retention.json, auto_reply_*.txt, legacy gui_endpoint.json when applicable.

---

Build

npm install
npm run build          # Vite frontend
cargo build --manifest-path src-tauri/Cargo.toml --release
npm run tauri build    # installers / .app / etc.

Develop:

npm run lint && npm run typecheck
npm run tauri:dev

Icons (from [src-tauri/icons/source/relay-icon.svg](src-tauri/icons/source/relay-icon.svg)):

npm run icons:build

CI: lint, typecheck, Vite, cargo fmt, clippy -D warnings, cargo test — see [docs/RELEASING.md](docs/RELEASING.md).

---

Documentation

| Doc | Content | | ------------------------------------------------------------ | -------------------------------------- | | [docs/HTTPIPC.md](docs/HTTPIPC.md) | HTTP API, timeouts, WSL path rewrite | | [docs/RELAYMCPSESSIONID.md](docs/RELAYMCPSESSIONID.md) | Session ID & tab labels | | [docs/TERMINOLOGY.md](docs/TERMINOLOGY.md) | Vocabulary + binaries / endpoint files | | [docs/RELEASING.md](docs/RELEASING.md) | Releases & CI |

---

Privacy

Data stays on device. All answers, logs, attachments, and settings are written only under your OS user paths. The GUI and MCP process communicate over 127.0.0.1 — nothing leaves your machine.

No telemetry. Relay ships no analytics SDKs, crash reporters, or remote instrumentation. Local files like feedback_log.txt may contain sensitive content — handle them accordingly.

---

Acknowledgements

Inspired by interactive-feedback-mcp. Relay replaces per-request subprocess UIs with a resident GUI and a Bearer-authenticated local HTTP layer.

---

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: andeya
• Source: andeya/ide-relay-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.