Skip to main content

🔌 MCP

Ludus MCP lets external agents send tasks to Ludus inside your open Unreal Editor. Connect Claude Code, Codex, Cursor, or any other app that supports the Model Context Protocol, and start work from there: Ludus runs each task on its own in the editor, and your agent reads the result.

  • Connection URL: https://mcp.ludusengine.com/mcp
  • Transport: HTTP
  • Sign-in: app.ludusengine.com, browser-based OAuth

Set up​

  1. Open your Unreal project with Ludus installed.
  2. Sign in to the same Ludus account your MCP client will use.
  3. In the Ludus panel, open Settings and enable Allow external agents (MCP). It is off by default. See Settings.
  4. Add the connection URL to your MCP client and complete the sign-in. Instructions for each client are below.

The Integrations page in the web app has the same instructions with copy buttons, and one-click install for Cursor and VS Code.

How it works​

Your external agent sends a task. Ludus runs it visibly in the editor panel, using its editor tools, including Python. Tasks can modify your project, so enable access only for agents you trust.

Ludus works through a task without further input, but approval requests still need your response inside Unreal. See Approvals & Safety.

New conversations can use Agent, Agent Max, or Agent Lite, depending on your plan. See Modes. Replies can take minutes, so keep Unreal open and connected until a task finishes.

Behind the connection, the Ludus MCP server hosts the connection and sign-in, the Ludus API routes tasks and stores conversation state, and the plugin receives tasks and runs them inside Unreal.

Credits​

Tasks sent through MCP are billed the same way as messages you send in the plugin. See Credits & Costs.

Available tools​

ToolWhat it does
list_editorsFinds connected editors and projects. Choose an editor_id when several are open.
send_messageStarts a conversation or continues an existing one. Busy conversations queue messages.
get_threadReads replies, pending messages, progress, errors, and approval requests. Check about every five seconds while a conversation is busy.
list_threadsFinds existing conversations by title.
cancelStops a reply and removes queued messages.
get_accountShows credits, plan, and available chat modes.

Connect your client​

Claude Code​

  1. Install Claude Code: npm install -g @anthropic-ai/claude-code
  2. Add Ludus MCP: claude mcp add --transport http ludus https://mcp.ludusengine.com/mcp
  3. Start Claude Code: claude
  4. Sign in by typing /mcp.

You can also add the connection to your project's .mcp.json file:

{
  "mcpServers": {
    "ludus": {
      "url": "https://mcp.ludusengine.com/mcp"
    }
  }
}

Codex​

  1. Install Codex: npm i -g @openai/codex
  2. Add Ludus MCP: codex mcp add ludus --url https://mcp.ludusengine.com/mcp
  3. If Codex does not ask you to sign in, run codex mcp login ludus.
  4. Start Codex: codex

You can also add the connection to ~/.codex/config.toml, then sign in with codex mcp login ludus:

[mcp_servers.ludus]
url = "https://mcp.ludusengine.com/mcp"

Cursor​

  1. Open Cursor Settings.
  2. Navigate to Tools & MCP.
  3. Click New MCP Server.
  4. Add the JSON configuration below.
  5. Cursor tries to connect and shows a Needs login prompt. Click it to authorize Cursor to access your Ludus account.

You can also add it to your project's .cursor/mcp.json file.

{
  "mcpServers": {
    "ludus": {
      "url": "https://mcp.ludusengine.com/mcp"
    }
  }
}

VS Code​

  1. Add the server from PowerShell:

    code --add-mcp '{\"name\":\"ludus\",\"type\":\"http\",\"url\":\"https://mcp.ludusengine.com/mcp\"}'

    On macOS or Linux:

    code --add-mcp '{"name":"ludus","type":"http","url":"https://mcp.ludusengine.com/mcp"}'

  2. Run MCP: List Servers, select ludus, and choose Start Server.

You can also add the connection to your project's .vscode/mcp.json file:

{
  "servers": {
    "ludus": {
      "type": "http",
      "url": "https://mcp.ludusengine.com/mcp"
    }
  }
}

Gemini CLI​

  1. Install Gemini CLI: npm install -g @google/gemini-cli
  2. Add Ludus MCP: gemini mcp add --transport http ludus https://mcp.ludusengine.com/mcp
  3. Start Gemini CLI: gemini
  4. Sign in by typing /mcp auth ludus.

You can also add the connection to ~/.gemini/settings.json:

{
  "mcpServers": {
    "ludus": {
      "httpUrl": "https://mcp.ludusengine.com/mcp"
    }
  }
}

Rider​

  1. Make sure Node.js is installed.
  2. Open Settings.
  3. Navigate to Junie -> MCP Settings.
  4. Click Add.
  5. Add the JSON configuration below.
{
  "mcpServers": {
    "ludus": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.ludusengine.com/mcp"]
    }
  }
}

Visual Studio​

  1. Add a new file at <SOLUTIONDIR>\.mcp.json or %USERPROFILE%\.mcp.json.
  2. Add the JSON configuration below.
  3. Click Manage Authentication above ludus in .mcp.json.
{
  "servers": {
    "ludus": {
      "url": "https://mcp.ludusengine.com/mcp"
    }
  }
}

Other clients​

If your client connects to remote HTTP servers, use the connection URL above. Otherwise, run Ludus MCP through mcp-remote (this needs Node.js):

{
  "mcpServers": {
    "ludus": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.ludusengine.com/mcp"]
    }
  }
}

Troubleshooting​

Your agent reportsWhat to do
editor_offlineNo editor is accepting external agents for this account. Check that your project is open, the plugin is signed in to the same account, and Allow external agents (MCP) is on.
editor_ambiguousMore than one editor is open. Call list_editors and pass an editor_id.
queue_fullThe editor has reached its limit of pending messages. Wait for them to finish, or cancel a conversation.
unavailableLudus is temporarily unavailable. Try again shortly.