xeno-mcp

An MCP server that lets AI agents interact with Roblox game clients — execute Lua scripts, capture game output, search community scripts, and manage client connections — all from your favorite AI tool.

Supports two modes:

• Xeno mode — direct integration with the Xeno executor
• Generic mode — file-based adapter that works with any executor (Solara, Velocity, etc.)

Why file-based and not DLL injection? Each executor uses its own internal API with different function signatures, memory layouts, and calling conventions — there's no universal DLL interface. Supporting executors via DLL would mean writing and maintaining a separate proxy for every single one, and any executor update could break it. The file-based approach works with any executor out of the box as long as it supports basic UNC functions (readfile, writefile, etc.), which virtually all of them do. It's also completely non-invasive — no hooking into executor internals, no binary compatibility issues, and no risk of triggering anti-cheat from foreign DLL injection.

What is Xeno? — A free, keyless Roblox script executor with multi-attach support. Grab it at xeno.now.

Table of Contents

• Architecture
• Prerequisites
• Build
• Setup — Xeno Mode
• Setup — Generic Mode
• MCP Configuration
• Tools
• Remote Spy
• Logs & Pagination
• HTTP API
• Server Flags
• Environment Variables
• Testing

Architecture

Two components work together:

1. HTTP Server (Rust/actix-web, port 3111) — manages client state, receives logs from injected Lua scripts, proxies to executor APIs
2. MCP Bridge (TypeScript, stdio) — translates MCP tool calls into HTTP requests and auto-starts the server

Xeno mode:

AI Agent ←—stdio—→ MCP Bridge ←—http—→ HTTP Server ←—http—→ Xeno API ←→ Roblox

Generic mode:

AI Agent ←—stdio—→ MCP Bridge ←—http—→ HTTP Server ←—file—→ Exchange Dir ←—poll—→ Loader (in executor) ←→ Roblox

The bridge spawns the HTTP server automatically — you don't need to start it manually.

Prerequisites

• Windows — Roblox executors are Windows-only
• Rust — builds the HTTP server (cargo)
• Node.js 18+ — runs the MCP bridge (npm)
• Git — to clone the repo
• An executor: Xeno for Xeno mode, or any executor with UNC support for generic mode

Build

git clone https://github.com/Lypt1x/xeno-mcp.git
cd xeno-mcp

# 1. Build the Rust HTTP server
cargo build --release

# 2. Build the MCP bridge
cd mcp-bridge
npm install
npm run build
cd ..

First Rust build takes a few minutes (pulls dependencies). Subsequent builds are fast.

The server binary is at target/release/xeno-mcp.exe. The bridge output is at mcp-bridge/dist/.

Setup — Xeno Mode

This is the default mode. Xeno has a built-in API that the server communicates with directly.

1. Build the project (see Build)
2. Add the MCP config to your AI agent (see MCP Configuration)
3. Open Xeno and inject into a Roblox client
4. Start your AI agent — the bridge starts the server automatically

That's it. The agent will detect Xeno clients and can execute scripts immediately.

Setup — Generic Mode

Generic mode works with any executor that supports basic UNC functions. Instead of a direct API, scripts are exchanged through the filesystem.

Requirements

Your executor must support:

• readfile(path) — read file contents
• listfiles(path) — list files in a directory
• isfile(path) — check if a path is a file
• delfile(path) — delete a file
• request({...}) — make HTTP requests
• getgenv() — global environment table

Setup

1. Build the project (see Build)
2. Find your executor's workspace folder (the directory where readfile/writefile operate)
3. Add the MCP config with generic mode env vars (see MCP Configuration)
4. Start your AI agent
5. Open your executor, inject into Roblox, and paste this into the executor:

   loadstring(game:HttpGet("http://localhost:3111/loader-script"))()
   

6. You'll see an in-game notification: "Loader connected" — you're ready to go

What the loader does

The loader script runs inside the executor and:

• Polls exchange/pending/ for new .lua script files every 200ms
• Executes scripts via loadstring() and deletes the file
• Captures all print/warn/error output and sends it to the server
• Sends heartbeats every 5 seconds to keep the connection alive
• Auto-reconnects if the server restarts (retries every 5s, notifies in-game)
• Automatically disconnects when the player leaves the game
• Prevents double-injection (safe to run multiple times)

Autoexec (optional)

To skip pasting the loadstring every time you inject, save it to your executor's autoexec folder:

1. Find your executor's autoexec folder (usually inside the workspace/root directory)
2. Create a file called xeno-mcp-loader.lua with this content:

   loadstring(game:HttpGet("http://localhost:3111/loader-script"))()
   

3. The loader will now connect automatically every time you inject

MCP Configuration

Add the following to your AI agent's MCP config. Replace the path with your actual clone location.

Xeno Mode

{
  "mcpServers": {
    "xeno-mcp": {
      "command": "npx",
      "args": ["-y", "C:/path/to/xeno-mcp/mcp-bridge"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "xeno-mcp": {
        "command": "npx",
        "args": ["-y", "C:/path/to/xeno-mcp/mcp-bridge"]
      }
    }
  }
}

{
  "mcpServers": {
    "xeno-mcp": {
      "command": "npx",
      "args": ["-y", "C:/path/to/xeno-mcp/mcp-bridge"]
    }
  }
}

Generic Mode

Add the XENO_MCP_MODE and GENERIC_EXECUTOR_WORKSPACE environment variables:

{
  "mcpServers": {
    "xeno-mcp": {
      "command": "npx",
      "args": ["-y", "C:/path/to/xeno-mcp/mcp-bridge"],
      "env": {
        "XENO_MCP_MODE": "generic",
        "GENERIC_EXECUTOR_WORKSPACE": "C:\\path\\to\\executor\\Workspace"
      }
    }
  }
}

The bridge automatically creates the exchange/pending/ and exchange/done/ subdirectories inside the workspace.

Optional: Shared Secret

To require authentication on all POST/DELETE endpoints:

{
  "env": {
    "XENO_MCP_SECRET": "your-secret-here"
  }
}

Tools

The MCP server exposes these tools to the AI agent:

Core Tools

ScriptBlox Integration

The agent enforces safety rules: unverified scripts require explicit user confirmation, obfuscated scripts trigger warnings, and key systems are flagged.

Remote Spy Tools

See Remote Spy for details.

Remote Spy

The remote spy intercepts Roblox remote calls (both incoming and outgoing) and logs them through the existing log system. It uses the dual-hook redirect pattern to avoid blocking game traffic.

Requirements

• Generic mode only — requires UNC hook functions (hookfunction, hookmetamethod, newcclosure, etc.) that are not available in Xeno mode
• In Xeno mode, the spy tools return an error explaining the UNC requirement
• Logger should be attached first for status messages

How It Works

1. attach_spy injects a Lua script that hooks FireServer, InvokeServer (via hookfunction) and __namecall (via hookmetamethod)
2. The __namecall hook redirects remote calls to the hookfunction'd versions instead of calling old() directly — this is the key pattern that avoids blocking game traffic
3. Passive OnClientEvent:Connect() listeners capture incoming server→client events
4. All intercepted calls are sent to POST /internal with event: "spy" and stored as log entries with source: "remote_spy"

Deduplication

By default, the spy deduplicates — only the first occurrence of each unique remote (by path + direction + method) is logged. This prevents flooding the log with 60+/frame calls in busy games.

To get all calls for a specific remote (including args), use spy_subscribe:

spy_subscribe("ReplicatedStorage.Remotes.SetAFK")

This makes the spy log every call to remotes matching that path. Supports partial matching — subscribing to "Remotes" matches all remotes under that path.

Use spy_unsubscribe to return a remote to dedup-only mode.

Querying Spy Logs

Spy logs use source: "remote_spy" and tags ["spy", "in"|"out"]:

get_logs(source="remote_spy")              — all spy logs
get_logs(source="remote_spy", tag="out")   — outgoing calls only
get_logs(source="remote_spy", tag="in")    — incoming calls only
get_logs(source="remote_spy", search="SetAFK") — specific remote

Cleanup

• detach_spy sends a disconnect script that restores all hooks and clears listeners
• The spy auto-cleans up when the player leaves the game
• The spy guards against double-injection: re-attaching disconnects the previous spy first

Logs & Pagination

Every script execution and all game output (print, warn, error) are captured as log entries.

Log Levels

Pagination

Logs are returned 50 per page by default (max 1000). The response includes:

{
  "logs": [...],
  "total": 247,
  "page": 1,
  "per_page": 50,
  "total_pages": 5,
  "has_more": true
}

Use page (1-indexed) to navigate, or offset for manual control.

Filters

All filters can be combined:

HTTP API

For direct integration without MCP:

All POST/DELETE endpoints require the X-Xeno-Secret header when --secret is set.

Server Flags

xeno-mcp [OPTIONS]

Options:
  -p, --port <PORT>                  Port to listen on [default: 3111]
  -b, --bind <ADDR>                  Bind address [default: 127.0.0.1]
      --console                      Print incoming logs to stdout
      --log-file <PATH>              Append logs to a file
      --secret <SECRET>              Require X-Xeno-Secret header on POST/DELETE
      --max-entries <N>              Max log entries in memory [default: 10000]
      --xeno-url <URL>               Xeno API URL [default: http://localhost:3110]
      --mode <MODE>                  Server mode: xeno or generic [default: xeno]
      --exchange-dir <DIR>           OS path for script exchange files [default: ./exchange]
      --executor-exchange-dir <DIR>  Exchange path as seen by the executor's filesystem

To run the server manually (useful for debugging):

./target/release/xeno-mcp --mode generic --exchange-dir "C:\Executor\Workspace\exchange" --executor-exchange-dir exchange --console

Environment Variables

Configure the MCP bridge via environment variables in your MCP config:

Advanced overrides (rarely needed):

Testing

Use the MCP Inspector to test tools interactively:

npx @modelcontextprotocol/inspector npx -y ./mcp-bridge

This opens a web UI where you can invoke each tool, inspect responses, and read resources.