Expose a Web game directly to browser AI tools

How it differs from gui-mcp

gua-webmcp

Runs in the exported game's page and talks to an engine-owned JavaScript port in that same tab. Use it for browser-native AI playtesting of Godot Web or Unity WebGL.

gui-mcp

Runs as a separate stdio MCP server and connects to a native game through WebSocket. Use it for desktop Godot or Unity Player/Editor automation.

Install and register

Install the browser packagepowershell

npm install gua-webmcp

Godot Web Export pagets

import { createGodotWebBridge, registerGuaWebMcp } from "gua-webmcp";

const registration = await registerGuaWebMcp(createGodotWebBridge());
if (!registration.supported) console.info(registration.error);

The engine port must exist before the bridge is created and tools are registered, because game-input capabilities are read once during registration. Load the engine export first, wait for window.__guaGodotWebPort, then call the no-argument createGodotWebBridge(). For Unity WebGL, wait for window.__guaUnityWebPort and call the no-argument createUnityWebGlBridge(). Each helper resolves its default global port name; do not pass the port object itself.

Prepare a Godot Web export

Install the combined Godot addon
Download gua-godot-addon-v*.zip from the latest Gua release. It contains the Windows DLL and both Debug and Release Web GDExtension WASM files.
Enable Extension Support
In the Web export preset, enable Extension Support and use the single-threaded export variant. Godot selects web.wasm32.single.debug or web.wasm32.single.release automatically.
Serve the export over HTTP(S)
Do not open the generated HTML directly from disk. Supply cross-origin isolation headers when required by the browser/export configuration.

Prepare a Unity WebGL build

The released com.link1345.gua-<version>.tgz already contains the WebGL native libraries and GuaWebMcp.jslib. The WebGL path is experimental. Its first bridge exposes semantic UI, World Object Tree, and enabled game-input capabilities, but does not advertise screenshot support.

What becomes available

The page registers Semantic UI reads/actions/waits, read-only World Object Tree tools, and only the Semantic Game Action or Raw Input tools whose engine pump is initialized. The released Godot and Unity built-in ports do not currently advertise screenshot support. A custom GuaInPagePort may opt in only when it implements a compatible drawable-frame readback path. Calls wait for request-correlated host completion instead of treating enqueue acceptance as success.

Security and lifetime

Browser ports always use the host's Player projection and Player action authorization. A local Debug Inspector cannot expose private data to WebMCP, and no tool can request Debug. Game input is denied by default until the host separately allows Player semantic or raw input. Each tab owns its registration and input session; timeout, caller cancellation, unregister, and engine shutdown release page-owned held input.