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
--connectmakes 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:
- Bevy window opens on the main thread
- MCP relay starts on port 9878 β you see:
MCP relay active on port 9878 (external MCP clients can connect to this window) - Nothing else runs in the window: no agent, no prompt
- When you prompt the agent in its own terminal:
- It reads its MCP config
- It spawns
localgpt-gen mcp-server --connect - The
--connectprocess connects to the relay on port 9878 - Tool calls flow through to the existing Bevy window
- 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]| Flag | Description |
|---|---|
--connect | Connect to an existing gen processβs MCP relay |
--connect 9878 | Connect to a specific port (default: auto-discover) |
--headless | Run without a window (for CI/batch generation) |
--mcp-relay | Start 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:
| Client | MCP 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 --connectStill 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.