dex-mcp

Debug and inspection tooling for Roblox projects, exposed as an MCP server so an AI agent can explore the instance tree, read/write properties, call remotes, and run Luau in a Roblox client driven by an executor.

Repository: https://github.com/972jesko/dex-mcp

Intended use: debugging, inspecting, and learning from your own Roblox projects locally. See GUIDELINES.md.

Install

npm install
npm run build

Run

node dist/index.js

On startup the server prints (to stderr) the local WebSocket URL and a shared token. The Luau bridge connects to that URL. Configure your MCP client to launch node /absolute/path/to/dist/index.js over stdio.

Configuration (environment variables)

Variable	Default	Purpose
DEX_MCP_HTTP	false	Remote mode. Bind 0.0.0.0, serve MCP over HTTP at /mcp, and point the bridge at wss://<host>. See Remote (hosted) mode.
PORT	—	Honoured before DEX_MCP_PORT (the var hosts like Railway inject).
DEX_MCP_PORT	8392	WebSocket hub port
DEX_MCP_TOKEN	auto-generated, persisted	Shared token required by the bridge. Generated once and saved (see DEX_MCP_TOKEN_FILE) so it stays stable across server restarts; set explicitly to pin it. Required in remote mode (container disks are ephemeral).
DEX_MCP_TOKEN_FILE	~/.dex-mcp/token	Where the auto-generated token is persisted.
DEX_MCP_ENABLE_WRITE	true	Enable set_property
DEX_MCP_ENABLE_REMOTES	true	Enable remote calling/spying
DEX_MCP_ENABLE_RUN_LUAU	true	Enable run_luau
DEX_MCP_RPC_TIMEOUT_MS	15000	Per-request timeout

401 Unauthorized from the bridge? The bridge baked in a token from an earlier server start. With a persisted token this no longer happens on restart; if you still see it, the bridge chunk is stale — stop it in your executor and re-run the loader one-liner so it fetches the current token.

Remote (hosted) mode

By default dex-mcp is local-only: the MCP server talks to its client over stdio and the hub binds 127.0.0.1, so the executor and the MCP client must share one machine. Remote mode lifts that constraint — the same process binds 0.0.0.0, exposes the MCP server over Streamable HTTP at /mcp, and serves the bridge a wss://<host> target — so a hosted instance (e.g. Railway) can sit between an executor and a remote MCP client.

Enable it with two env vars on the host:

Var	Value
DEX_MCP_HTTP	true
DEX_MCP_TOKEN	a fixed secret you choose (the disk is ephemeral, so pin it)

PORT is injected by the platform and honoured automatically. Then:

• MCP client → point it at https://<host>/mcp, authenticating with the token via Authorization: Bearer <token> (or ?token=<token>).
• Executor (Roblox side) → loadstring(game:HttpGet("https://<host>/bridge?token=<token>"))(). In remote mode /bridge is token-gated (the served chunk embeds the token, so a public /bridge would leak it) and injects wss://<host> as the bridge's connect target.
• GET /health returns 200 for the platform healthcheck.

⚠️ Security. /mcp runs arbitrary Luau (run_luau), writes properties, and fires remotes in the connected client. In remote mode that capability is reachable over the public internet, gated only by the shared token. Use a long random DEX_MCP_TOKEN, and only against a game you own.

The bridge (Roblox side)

The Luau bridge runs inside a script executor and connects back to this server.

1. Start the server: node dist/index.js. It prints a loader line.
2. In your executor (in a game you own / are allowed to inspect), run:

   loadstring(game:HttpGet("http://127.0.0.1:<port>/bridge"))()
   

   The server injects the per-run auth token into the served script automatically.
3. The bridge connects over WebSocket and answers the MCP tools. It auto-reconnects if the server restarts.

The bridge is assembled on the fly from bridge/codec.luau, bridge/core.luau, and bridge/dex-bridge.luau. The codec and core are unit-tested with lune: npm run test:bridge.

Executor requirements

• WebSocket.connect (UNC/sUNC standard).
• loadstring for run_luau.
• hookmetamethod/getrawmetatable/getnamecallmethod/newcclosure for the remote spy (capability-gated — the bridge degrades gracefully without them).