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

Related MCP server: dex-mcp

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)

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:

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).