MCP Relay

MCP RelayπŸ”—

When LocalGPT Gen runs interactively with --mcp-relay, an MCP client outside it β€” Claude Code, Gemini CLI, Codex, an editor β€” drives the same Bevy window you’re looking at. Gen runs no agent and is nobody’s model backend: the agent runs in its own terminal with its own login, and reaches the window through the relay.

The ProblemπŸ”—

Without the relay, an MCP client configured with localgpt-gen mcp-server spawns its own process. This creates a second Bevy window that opens, renders the world, and immediately closes β€” while the original window stays empty.

  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     spawns      β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚  MCP client  │────────────────►│ localgpt-gen      β”‚ ← second window!
  β”‚  (an agent)  β”‚   MCP stdio     β”‚ mcp-server        β”‚
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                 β”‚ (NEW Bevy + scene) β”‚
                                   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚  localgpt-gen (interactive)       β”‚ ← your window (empty)
  β”‚  Bevy window you're looking at    β”‚
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

The Fix: MCP RelayπŸ”—

LocalGPT Gen starts a TCP relay server alongside the Bevy window. When the client spawns localgpt-gen mcp-server --connect, it connects to the relay instead of creating its own Bevy instance. All tool calls route to your existing window.

  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚  localgpt-gen (interactive)                                       β”‚
  β”‚                                                                   β”‚
  β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   GenBridge    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”    TCP :9878            β”‚
  β”‚  β”‚ Bevy 3D    │◄─────────────►│ MCP     │◄──────────────┐        β”‚
  β”‚  β”‚ Window     β”‚  (in-process)  β”‚ Relay   β”‚               β”‚        β”‚
  β”‚  β”‚            β”‚                β”‚ Server  β”‚               β”‚        β”‚
  β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜               β”‚        β”‚
  β”‚        β–²                                                β”‚        β”‚
  β”‚        β”‚ renders scene                                  β”‚        β”‚
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”˜
           β”‚                                                β”‚
           β”‚                          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
           β”‚                          β”‚  stdio ↔ TCP bridge β”‚
           β”‚                          β”‚                     β”‚
           β”‚                     β”Œβ”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”      β”‚
           β”‚                     β”‚ localgpt-gen       β”‚      β”‚
           β”‚                     β”‚ mcp-server         β”‚β—„β”€β”€β”€β”€β”€β”˜
           β”‚                     β”‚ --connect           β”‚  TCP relay
           β”‚                     β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
           β”‚                          β”‚ MCP stdio
           β”‚                     β”Œβ”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
           β”‚                     β”‚  Claude CLI /      β”‚
      you see the                β”‚  Gemini CLI /      β”‚
      world here                 β”‚  Codex             β”‚
                                 β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Key points:

  • Only one Bevy window exists β€” the one you see
  • The relay server listens on TCP port 9878
  • --connect makes the MCP server process a thin stdio↔TCP bridge
  • Tool calls travel: CLI β†’ MCP stdio β†’ bridge β†’ TCP β†’ relay β†’ GenBridge β†’ Bevy
  • Results travel the reverse path back to the CLI

How It WorksπŸ”—

When you run localgpt-gen --mcp-relay:

  1. Bevy window opens on the main thread
  2. MCP relay starts on port 9878 β€” you see:
    MCP relay active on port 9878 (external MCP clients can connect to this window)
  3. Nothing else runs in the window: no agent, no prompt
  4. When you prompt the agent in its own terminal:
    • It reads its MCP config
    • It spawns localgpt-gen mcp-server --connect
    • The --connect process connects to the relay on port 9878
    • Tool calls flow through to the existing Bevy window
  5. You see the world being built in real-time in your window

Gen has no prompt of its own: the relay, mcp-server, or a live package’s API is how the window is driven, and several clients may share one window.

ConfigurationπŸ”—

Start the relayπŸ”—

localgpt-gen --mcp-relay

Without the flag no port is opened and no relay message is shown.

Point the client at itπŸ”—

Each client keeps its own MCP config; LocalGPT writes none of them.

Claude CodeπŸ”—

Add to project-level .mcp.json:

{
  "mcpServers": {
    "localgpt-gen": {
      "command": "localgpt-gen",
      "args": ["mcp-server", "--connect"]
    }
  }
}

Gemini CLIπŸ”—

Add to ~/.gemini/settings.json or workspace .gemini/settings.json:

{
  "mcpServers": {
    "localgpt-gen": {
      "command": "localgpt-gen",
      "args": ["mcp-server", "--connect"]
    }
  }
}

CodexπŸ”—

Add to ~/.codex/config.toml:

[mcp_servers.localgpt-gen]
command = "localgpt-gen"
args = ["mcp-server", "--connect"]

A config that already names localgpt-gen mcp-server without --connect spawns a window of its own; add "--connect" to its args to reach the one you have open.

Standalone MCP modeπŸ”—

To run Gen as a standalone MCP server β€” the client spawns the whole of Gen, window included β€” use mcp-server without --connect:

localgpt-gen mcp-server

This is for desktop apps (Claude Desktop, Codex Desktop) and editors (VS Code, Zed, Cursor) where you don’t need the interactive terminal. See MCP Server for details.

CLI FlagsπŸ”—

localgpt-gen mcp-server --connect [PORT]
FlagDescription
--connectConnect to an existing gen process’s MCP relay
--connect 9878Connect to a specific port (default: auto-discover)
--headlessRun without a window (for CI/batch generation)
--mcp-relayStart the MCP relay beside the window (the interactive localgpt-gen)

Port auto-discovery reads from $XDG_RUNTIME_DIR/localgpt/gen-mcp-relay.port, which the interactive gen process writes on startup.

MCP clientsπŸ”—

Any MCP client that can spawn a stdio server. The three that come up most:

ClientMCP config location
Claude Code.mcp.json in the folder it starts in, or its user settings
Gemini CLI.gemini/settings.json there, or ~/.gemini/settings.json
Codex~/.codex/config.toml

TroubleshootingπŸ”—

β€œNo relay port specified and no running gen process foundβ€πŸ”—

The --connect process can’t find the relay. Make sure a window with the relay is open first:

# Terminal 1: the window, with the relay
localgpt-gen --mcp-relay

# Terminal 2: the MCP connect process finds it automatically
localgpt-gen mcp-server --connect

Still seeing two windowsπŸ”—

Check the client’s own MCP config (.mcp.json, .gemini/settings.json, ~/.codex/config.toml): the entry should have ["mcp-server", "--connect"] in its args. If it shows ["mcp-server"] without --connect, the client is spawning a window of its own.

Relay port conflictπŸ”—

If port 9878 is in use, the relay picks a random available port. Check the startup log for the actual port:

MCP relay active on port 51234 (external MCP clients can connect to this window)

The --connect flag auto-discovers the port, so this usually isn’t a problem.