rex-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@rex-mcp start a new session and run the test suite"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
rex-mcp
MCP server that lets an AI assistant see and manage a
Rex server through the rex CLI.
It can read any session and writes only to sessions it created or that you
allowlist.
Install
Copy this prompt into your AI assistant (Claude Code, OpenCode, Codex, Cursor or any other assistant that can run shell commands and register MCP servers) on the machine that runs Rex:
Install the rex-mcp MCP server from https://github.com/norbertgrzenkowicz/rex-mcp and add it to your own MCP configuration. Steps:
1. Check prerequisites and fix or stop with a clear message if one is missing:
- `node --version` is 26 or newer. If it is older, install Node 26 first (for example `nvm install 26 && nvm use 26`) and ask me which version manager I use if unsure.
- `rex` is on PATH (`command -v rex`) and a Rex server is running (`rex ls --json` succeeds).
- `git` and `npm` are available.
2. Clone the repo to ~/rex-mcp (or ask me for another path) and build it:
git clone https://github.com/norbertgrzenkowicz/rex-mcp.git ~/rex-mcp
cd ~/rex-mcp && npm ci
`npm ci` builds `dist/` through the `prepare` script.
3. In the clone directory, copy the example config if no config exists yet:
cp -n rex-mcp.config.example.json rex-mcp.config.json
Leave the defaults (writeAllowlist empty, allowLua false, allowClientActions false) unless I ask otherwise.
4. Register an MCP server named "rex" in your own MCP config as a stdio server with command `node` and argument `~/rex-mcp/dist/stdio.js`, written as an absolute path. Use your CLI if you have one (for Claude Code: `claude mcp add rex -- node "$HOME/rex-mcp/dist/stdio.js"`), otherwise edit your MCP config file. Show me the change you made.
5. Optional, only if I say I want remote assistants to reach it over HTTP: this needs `uv` (`brew install uv` or `pipx install uv`). Run
uvx mcp-proxy --host <listen-ip> --port 8787 -- node ~/rex-mcp/dist/stdio.js
and tell me the URLs (http://<listen-ip>:8787/mcp for streamable HTTP, /sse for SSE). Plain HTTP has no authentication, so it belongs on localhost or a private network. Ask me which IP to bind to; never bind to a public interface without asking.
6. Verify: restart your MCP client, then call the `rex_status` tool and the `rex_list` tool with kind "sessions". Report the Rex server version and the session count. Do not send text, run commands or kill anything in existing sessions.Manual install
Requires Node 26 or newer and rex on PATH.
git clone https://github.com/norbertgrzenkowicz/rex-mcp.git /path/to/rex-mcp
cd /path/to/rex-mcp
npm ci
cp -n rex-mcp.config.example.json rex-mcp.config.json
claude mcp add rex -- node "$PWD/dist/stdio.js"Any other MCP client: add this entry to your MCP configuration and point
args at your clone.
{
"mcpServers": {
"rex": {
"command": "node",
"args": ["/path/to/rex-mcp/dist/stdio.js"]
}
}
}From another machine over SSH:
claude mcp add rex -- ssh <host> node /path/to/rex-mcp/dist/stdio.jsOver HTTP for remote assistants, on the Rex machine:
uvx mcp-proxy --host <listen-ip> --port 8787 -- node /path/to/rex-mcp/dist/stdio.jsPlain HTTP has no authentication. Bind it to localhost or a private network.
Update
cd /path/to/rex-mcp
git pull
npm cinpm ci runs the prepare script, which rebuilds dist/. Restart the
process that is serving the old build. On the machine that publishes rex-mcp
over HTTP, that process is the systemd user service rex-mcp-http
(uvx mcp-proxy in front of node …/dist/stdio.js):
systemctl --user cat rex-mcp-httpExecStart names the install. In that directory, after the pull above:
systemctl --user restart rex-mcp-http
systemctl --user status rex-mcp-http --no-pager
journalctl --user -u rex-mcp-http -n 40 --no-pagergit pull does not restart the service. If the unit sets REX_MCP_CONFIG,
a rex-mcp close hook has to set it too, or the hook will not see the same
ownership file. systemctl --user show rex-mcp-http -p Environment -p EnvironmentFiles
prints what the service sets.
Remove
Remove the server from your MCP client (claude mcp remove rex, or delete the
rex entry from your MCP configuration), then delete the clone if you no
longer need it.
Related MCP server: Create app hosting
What it does
rex-mcp speaks MCP over stdio and runs every Rex operation through the rex
CLI, the supported Rex surface. An assistant on another machine can start it
over SSH, or reach it over HTTP through a proxy such as mcp-proxy.
DESIGN.md has the full design.
Then ask your assistant to capture the last lines of a block, start a session and run the test suite in it, or wait for a long job to exit.
Tools
Tool | Access |
| read |
| read |
| create |
| write |
| depends on the method or action |
DESIGN.md describes each tool's arguments.
Closing blocks when the work finishes
A one-off command goes through rex_run with wait_seconds. The call waits for the command, returns its screen output, and closes the block. Rex closes the window as well when that block was the last one in it. Set keep_open to true to leave the block up after it exits. That is the opt-out for a dev server or an interactive agent.
Without wait_seconds, rex_run returns as soon as the block exists. The block stays while the program runs. Rex closes it when the program exits, unless keep_open is true. A wait that times out leaves the block running; close it with rex_block_close if you are done with it.
Nothing is closed for being idle. A long-lived program (Claude Code, OpenCode, a server) stays until it exits or its creator closes it.
When that program is finished it can close the block it is running in:
node /path/to/rex-mcp/dist/stdio.js closerex-mcp close does the same thing when the install is on PATH. It only closes the block named by REX_BLOCK in the session named by REX_SESSION (the variables Rex sets inside a terminal). It takes no target argument. It refuses, and does not change anything, when:
those variables are missing
a parent process is
claude --remote-controlorclaude remote-controlit is running under tmux session
claude-rcthe session label is
wispy-fjord, or a label inprotectedSessionLabelsthe session was not created by rex-mcp and this block was not created by it
If the session was created by rex-mcp and this was its last block, the session is destroyed too. An allowlisted session is never destroyed; only a block rex-mcp created there is closed.
Claude Code can run it when a session ends. This belongs in the user or project settings on the Rex machine. Stop fires after every turn, so it closes the block while the agent is still in use. SessionEnd fires when the Claude session exits:
{
"hooks": {
"SessionEnd": [
{
"hooks": [
{
"type": "command",
"command": "node /path/to/rex-mcp/dist/stdio.js close"
}
]
}
]
}
}If the systemd unit sets REX_MCP_CONFIG, put the same variable in the hook command so the hook reads the same ownership file. The hook is safe to install globally: outside a block rex-mcp created, and under the protected setups above, the command exits 2 and closes nothing. OpenCode and other agents run the same command from their own session-end hook, or as the last step of a one-shot task.
Safety model
Reads are always allowed, on any session.
rex_capturereturns terminal scrollback, so a connected assistant can read anything a session has printed, including secrets. Connect it only to an assistant you trust with that machine.Writes need a target session that rex-mcp created or that
writeAllowlistnames. A write without a session is refused.Sessions created through rex-mcp are owned. Blocks it creates are recorded too, including blocks in an allowlisted session. Ownership survives restarts through
stateFile.rex-mcp closeonly closes the block it is running in, and only when that block or its session was created by rex-mcp. It never toucheswispy-fjord, aclaude-rctmux session, or anything underclaude --remote-control.Server, host, Tailscale and client-control API methods are blocked unless
unblockMethodslists them.Lua (
allowLua) and actions performed by a connected Rex app (allowClientActions) are off by default.rex-mcp never passes
--focus=true, so the Rex app keeps its focus.Every
rexchild runs withoutREX_SESSION,REX_BLOCK,REX_WINDOWandREX_CLIENT, so starting rex-mcp inside a Rex pane does not make that pane the default target.
A refused call returns an MCP tool error whose text starts with policy: and
names the rule.
Config
The config file is $REX_MCP_CONFIG if set, otherwise rex-mcp.config.json
in the repo directory. A missing default file means every default applies.
Unknown fields are rejected.
Field | Default | Meaning |
|
| Session IDs or labels rex-mcp may write to besides the ones it created. |
|
| Blocked API methods to allow, such as |
|
| Allow |
|
| Allow actions performed by a connected Rex app, and |
|
| Where created sessions and blocks are kept. Relative paths resolve against the repo directory. |
|
| Extra session labels |
|
| The |
| unset | Passed as |
Test
npm testnpm test builds, runs the unit tests, then the integration test. The unit
tests need no Rex server. The integration test does: it creates a session
named rex-mcp-test-<random>, runs every tool against it and kills it at the
end. It checks that a waited rex_run returns output and closes its block,
that keep_open leaves the block, that rex-mcp close removes a block this
server created, and that the same command refuses a session that already
existed. It checks that those pre-existing sessions are unchanged and that
writes to them are refused.
License
MIT. See LICENSE.
Available Tools
18 toolsrex_action_doB
Perform an action (rex do NAME --args JSON) or run Lua (script). Block actions need a writable session; init.lua actions and scripts need allowLua; client actions need allowClientActions.
Inputs: args, name, block, client, +2 more.
rex_actions_listC
Actions the server offers (init.lua and block types), or those a client reported with client.
Inputs: client.
rex_api_callB
Call any API method (rex api call). Policy class comes from the method table; writes need an owned or allowlisted session via session or args.session_id.
Inputs: method (required), args, session.
rex_api_describeB
Schemas and examples for one API method (rex api describe --json).
Inputs: method (required).
rex_api_listB
API methods the server offers, each tagged with its rex-mcp policy class.
Inputs: no named parameters.
rex_block_closeB
Close a block and end its program (rex block close). Rex closes the window too when that was its last block. Never closes a block for being idle, and never closes any other block.
Inputs: block (required), session.
rex_block_infoB
Block details and methods (rex block inspect), plus the terminal process state.
Inputs: block, session.
rex_captureB
Screen and scrollback of a terminal block. Without block, the focused block of the session's default window.
Inputs: block, format, unwrap, session, +2 more.
rex_events_pollA
Long-poll buffered Rex server events after cursor (0 = oldest). Returns events and the next cursor; dropped: true means events after your cursor fell out of the buffer.
Inputs: limit, types, cursor, session, +1 more.
rex_listB
List sessions, windows, blocks, or clients. session is required for windows and blocks.
Inputs: kind (required), session.
rex_runA
Run a command in a new block (a new window, or a split beside anchor_block). Never takes focus. With wait_seconds, wait until the command exits, return its screen as output, and close the block (and its window, when this block was the only one). That is the default for a one-off command. Set keep_open true to leave the block up after it exits, for a dev server or an interactive agent. If the wait times out, the program is still running and the block stays open; close it with rex_block_close if you are done with it. Without wait_seconds the call returns once the block exists and does not close it. Rex closes that block when the program exits, unless keep_open is true. Nothing is closed for being idle. A long-lived program closes its own block when it finishes by running rex-mcp close (see the README). That command refuses wispy-fjord, tmux session claude-rc, and claude --remote-control.
Inputs: command (required), cwd, label, ratio, +5 more.
rex_send_keysB
Press keys in a terminal (rex send-key), e.g. ["ctrl+c"] or ["enter"].
Inputs: keys (required), block, session.
rex_send_textB
Type text into a terminal (rex send, text on stdin). enter: true presses Return afterwards.
Inputs: text (required), block, enter, session.
rex_session_createA
Create a session (rex new). rex-mcp owns it, so it may write to it. Returns its ID and first block ID. The session stays up for as long as its programs do; it is not closed for being idle. Prefer rex_run with wait_seconds for a one-off command, which closes that block when the command exits. A program in this session can close its own block when it finishes by running rex-mcp close.
Inputs: cwd, label, window, command.
rex_session_killB
Kill a session (rex kill) and drop it from the owned set.
Inputs: session (required).
rex_session_viewC
Snapshot of a session: windows, layouts, blocks, focus (session.view).
Inputs: session (required).
rex_statusA
Rex server identity and version, the sessions rex-mcp owns, and the active policy flags.
Inputs: no named parameters.
rex_waitA
Wait on a block. until: exit waits for the terminal's program to exit; until: match polls the capture for pattern (a JS regex). Returns {done, timed_out, exit_code?, match?}.
Inputs: block (required), until (required), pattern, session, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools target a distinct resource and action, such as capture vs. block_info and send_text vs. send_keys. There are a few areas an agent could hesitate over, especially status/list/session_view and actions vs. API methods, but the descriptions generally clarify the boundaries.
All names use the rex_ prefix and snake_case, which keeps them readable. However, the ordering is mixed: some are resource_action (session_create, api_call), some are action_resource (send_text, send_keys), and some are bare verbs (list, run, wait).
At 18 tools, the surface is borderline heavy for this domain. The generic API and action layers add useful power, but they also contribute overlapping discovery/execution paths that make the set feel larger than strictly necessary.
The suite covers session/block lifecycle, input/output, waiting, event polling, and generic API/action escape hatches, so agents are unlikely to hit dead ends. Explicit gaps exist around finer-grained window/focus management, but rex_api_call and actions can generally compensate.
Maintenance
Related MCP Connectors
Connect AI assistants to explicitly paired computers, servers, and VMs for permitted remote actions.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with Replit workspaces directly, including managing repls, file operations, environment variables, and deployments without constant user intervention.244MIT

Create app hostingofficial
AlicenseNot gradedqualityCmaintenanceEnables AI assistants to create projects, deploy files, container images, or Git repositories, attach domains, set write-only secrets, add Postgres, read logs, metrics, and failure summaries, and roll back.Apache 2.0- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to inspect, query, and diagnose projects, deployments, releases, runbooks, tasks, tenants, Kubernetes resources, machines, certificates, accounts, and interruptions, with optional write operations and read-only safeguards.547 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to inspect, query, and diagnose an Octopus instance and, when write access is enabled, create releases, deploy releases, run runbooks, and adjust feature toggles.547 npmMIT