Relay Remotify MCP

remotify-mcp

MCP server that gives any MCP-compatible host a remote_exec tool backed by a remotify.run relay.

Runs on your machine; zero cost to the relay server.

Install

Most users don't install - the MCP hosts below all launch it via npx:

npx -y remotify-mcp@latest

Or clone this repo and run npm install in mcp/ if you want to hack on it.

Wire it into your MCP host

Every host below launches the same command; only the config file differs. If a host does not pick the server up, check its own docs for where it reads MCP config from.

Claude Code

claude mcp add -s user remotify -- npx -y remotify-mcp@latest

-s user registers it for every working directory instead of only the one you ran the command in. claude mcp list shows it; /mcp inside a session shows the live status and the exposed tools.

Codex CLI

~/.codex/config.toml:

[mcp_servers.remotify]

command = "npx" args = ["-y", "remotify-mcp@latest"]

OpenCode V2

opencode mcp add remotify --global -- npx -y remotify-mcp@latest

Requires Node.js 18+ with npx. --global registers the server for every project in ~/.config/opencode/opencode.jsonc; omit it for the current project only. No account, API key, or global npm install is needed.

Check the connection with opencode mcp list or /mcps inside OpenCode. Ask OpenCode to call remote_session_info and show both connection one-liners, then paste your chosen line on the remote. Supervised mode asks for approval before each command; auto mode executes without approval.

For a self-hosted relay, add environment to the server entry under mcp.servers (OpenCode V2 uses environment, not env):

{

"$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "remotify": { "type": "local", "command": ["npx", "-y", "remotify-mcp@latest"], "environment": { "REMOTIFY_URL": "https://remotify.example.com" } } } } }

Cursor

~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:

{ "mcpServers": { "remotify": { "command": "npx", "args": ["-y", "remotify-mcp@latest"] } } }

Restart Cursor afterwards.

Windsurf

~/.codeium/windsurf/mcp_config.json, same shape:

{ "mcpServers": { "remotify": { "command": "npx", "args": ["-y", "remotify-mcp@latest"] } } }

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows:

{ "mcpServers": { "remotify": { "command": "npx", "args": ["-y", "remotify-mcp@latest"] } } }

Restart the app afterwards.

Gemini CLI

~/.gemini/settings.json:

{ "mcpServers": { "remotify": { "command": "npx", "args": ["-y", "remotify-mcp@latest"] } } }

Anything else

Continue, Cline, Roo Code, Zed, VS Code's built-in MCP and the rest take the same command plus args pair in a file they each document. Drop the snippet in and you are done.

Pointing at a self-hosted relay

Out of the box this talks to the public relay at https://relay.remotify.run. For your own instance add one env var to your host's configuration (see the OpenCode V2 example above for its environment field):

"env": { "REMOTIFY_URL": "https://remotify.example.com" }

What the host has to render

The connect one-liners travel in an ordinary text content block on the tool result, because that is the one thing every host above passes to the model unchanged. Nothing in this server depends on host-specific machinery: not Claude Code hooks, not notifications/progress or notifications/message, not MCP resources, not elicitation. The hook and the desktop notification described further down are extras for hosts that support them, never the only path.

Environment

Tools exposed

• remote_exec(command) - pushes command to the relay, waits for the listener to run it, returns combined stdout+stderr as plain text.
• remote_session_info() - leads with both ready-to-paste one-liners (supervised and auto) and a sentence on what each does, then the session JSON: key, URLs and TTL. Minting the session lazily on this call is enough to hand the user everything they need to connect a listener.
• remote_session_reset({rotate?}) - recovery escape hatch. Default: clears wedged relay state in place (queued cmd/result + in-flight marker); the key and a connected listener keep working. {"rotate": true}: purges the current session and mints a brand-new key (the user must re-paste the new one-liner). Normally unnecessary - remote_exec auto-recovers on its own (see below).

Auto-recovery from a wedged session

A listener killed mid-command without a chance to notify the relay (kill -9, closed terminal, host reboot) used to leave the session wedged: every new command returned [busy] for a command the current session never issued, and the only way out was hand-posting a dummy result and reloading the MCP. That state now clears itself:

• Relay-side: the moment any listener (re)connects and polls for work, the relay detects the orphaned in-flight marker, clears it, and queues a synthetic [remotify: ...] result for whoever was waiting.
• MCP-side: when a new command hits the busy-guard and the marker is provably stale (listener heartbeat newer than the pickup by REMOTIFY_STALE_GRACE_S) or older than REMOTIFY_MAX_INFLIGHT_MS, the MCP resets the session state itself (POST /api/session/{key}/reset, with a manual-clear fallback for older relays) and proceeds with the new command, prefixing the response with [recovered].

A genuinely long-running command is not affected: while its listener is busy executing, the heartbeat cannot be newer than the pickup, so nothing clears before REMOTIFY_MAX_INFLIGHT_MS.

One wedge variant cannot self-clear: the listener died mid-command (heartbeat frozen at pickup, indistinguishable from a genuine long run) and stays under the in-flight ceiling. Recovery then requires the user to reconnect the runner, so the [busy] response includes the paste one-liners and tells the assistant to relay them - reconnecting triggers the relay-side self-heal above.

Relay-served message wording

Every runtime string remote_exec returns to the assistant ([pending], [busy], [recovered], the paste one-liners, ...) is rendered from a template table. The relay may serve replacements for any subset of keys on the session payload (mcp_messages.templates, maintained in the relay repo at php/app/mcp-messages.json), so wording improvements ship with a relay deploy and reach every client - including stale cached installs - on their next session, without an npm release. The package keeps the full table baked in as a fallback for older relays and offline failure modes.

Deliberately not relay-served: tool names, schemas, and descriptions. Hosts and users grant approval based on those; they only change through versioned npm releases.

How remote_exec handles a missing listener

The MCP server has no channel to show text to the user mid-tool-call (Claude Code, Cursor, etc. don't render notifications/progress or notifications/message from an MCP server during a tool call). Elicitation dialogs work but can't be closed server-side on current clients, which leaves stale prompts in chat.

There is a second constraint that shaped the current design: text the assistant writes between tool calls is not reliably shown either. Claude Code collapses it into a one-line "summarized" stub, and other hosts truncate or hide it. An assistant that "relays the one-liners, then keeps polling" has therefore relayed nothing the operator can paste. The only text a host shows in full is the final message of the assistant's turn.

So remote_exec distinguishes two [pending] cases:

1. Mints the session if this is the first call, then pushes the command so it is queued on the relay whatever happens next.
2. First command of a session no listener has ever polled: the tool answers straight away, with no waiting at all. Nothing can pick the command up until the user pastes a runner line and they have not been shown one yet, so waiting would only burn seconds. The response is a [pending] carrying BOTH paste one-liners (supervised and auto) and telling the assistant to stop, end its turn, and make those two lines, verbatim in a fenced code block, its final message. The command stays queued. When the user pastes a one-liner the listener picks it up and runs it; on the user's next message the assistant calls remote_exec again with the same arguments and collects the output. The server carries state across turns, so the command is not re-queued and will not execute twice.
3. Otherwise the tool polls for ~5s (REMOTIFY_CHUNK_MS). If the listener picks the command up in that window it waits for the result and returns it. Most calls finish here.
4. Still no listener on a later call: the same [pending] with both lines. They are repeated on every no-listener [pending], on dead-listener [busy] wedges, on session renewal, and in the give-up error, so an assistant that ignored the stop once still has them on the next response.
5. Listener online (fresh heartbeat) but pickup not yet confirmed: the tool returns a [pending] without one-liners and asks for a silent same-args retry, giving up only after about 10 consecutive responses. Once the relay confirms the command is executing (cmd_in_flight) the response switches to [in-flight], which has no retry cap at all.
6. Relay unreachable rather than listener missing: when not one status probe got through, the response says so instead of sending the user off to paste a line that is not what is broken. A relay that cannot be reached at all (DNS, refused, timeout) and a retired endpoint answering 426 each get their own message naming the URL and what to change.

Every [pending] also restates the hard rule: never fall back to ssh, scp, or any other transport, and never try to start the listener yourself. Operators pick remotify precisely so that no agent gets shell access; an assistant that works around a missing listen