Connect OpenBeam to Codex or Claude

Use the same remote MCP URL for every user:

https://cloud.openbeam.world/mcp

You can connect before starting a game. After you approve session control,
your AI app can start OpenBeam and return a player link. Open that link promptly
and keep its player tab open while the AI app controls it. The URL follows
the signed-in account's current game, including games placed on another VM.
The Play dashboard also provides a Copy MCP link button.

Codex

Add the URL as a remote MCP server in Codex and sign in with OpenBeam when
prompted. The OpenBeam page shows the connecting app, its return address,
and the game and cloud session permissions before offering Connect or Cancel.

For the Codex CLI:

codex mcp add openbeam --url https://cloud.openbeam.world/mcp
codex mcp login openbeam

An OAuth Client ID does not need to be entered manually: OpenBeam supports
dynamic registration. If an earlier attempt reported a registration failure,
start the connection again after the 2026-09-29 API update.

See Codex MCP documentation.

Claude

In Claude's Customize → Connectors, choose Add custom connector,
name it OpenBeam, and enter the URL above. Choose Connect, sign in with
OpenBeam, and approve the connection you started.

See Claude's remote MCP connector guide.
Availability depends on the account's connector settings and workspace policy.

What the connection can do

An approved account connection can list, start, and end its owner's cloud
sessions, load maps, spawn and control vehicles, inspect simulation state,
and take screenshots. Starting a session uses the account's available play
time and follows its membership, invitation, duration, capacity, and concurrent
session limits. It does not grant access to billing settings or pool administration.
No cloud credentials or session bearer tokens need to be pasted into an AI app.

Connections approved before session controls were added retain game-control
permission only. Disconnect and reconnect the app, then approve the permission
to start and end sessions. A connection approved for a specific game remains
limited to that owned session.

The account URL provides these tools even when no game is running:

The first three require session-control approval. cloud_game_tools and
cloud_game_call let an app continue after launching a game without reconnecting.
Keep the returned player URL private: it grants access to that game's stream.

Example tool calls:

{"name":"cloud_session_start","arguments":{"width":1280,"height":720,"fps":60}}

{"name":"cloud_game_tools","arguments":{"session_id":"YOUR_SESSION_ID"}}

{"name":"cloud_game_call","arguments":{"session_id":"YOUR_SESSION_ID","name":"status","arguments":{}}}

{"name":"cloud_session_end","arguments":{"session_id":"YOUR_SESSION_ID"}}

Disconnect an app from the Play dashboard to revoke its connection. Access
tokens last one hour; rotating refresh tokens and grants last up to 30 days.
Revoking the browser identity that approved a connection also invalidates
that connection. Signing out locally does not itself revoke other apps;
use Disconnect for that.

If the account has no active game, use cloud_session_start and open its
player link. If it has multiple games, use cloud_session_list and pass the
chosen session_id to the game tools. The specific game's
/v1/sessions/<id>/mcp URL also remains available; its corresponding approval
is limited to that owned, active session.

Operator notes

The Session API publishes protected-resource metadata and OAuth authorization
server metadata. Registration accepts HTTPS callbacks and native loopback
callbacks. Authorization codes require S256 PKCE, exact callback and resource
binding, expire after two minutes, and can be spent once. OAuth tokens are
accepted only by MCP routes. Reused refresh tokens revoke the grant.

OAuth state survives API restarts in session-api.db.mcp-oauth, next to the
main session database. Include both databases in restricted SQLite-consistent
backups. Codes, access tokens, refresh tokens, and client secrets are stored
as hashes; the databases still contain private account and grant metadata.

Caddy exposes /mcp, /oauth/*, and the OAuth discovery paths. Metrics and
readiness endpoints stay private. When hot-reloading a file bind mount after
replacing its host file, stage the current configuration inside the Caddy
container, validate it, and reload that staged path. This avoids reloading a
stale mounted inode and permits active games to continue.

Previous validation on 2026-09-29: 699 API tests, 20 console tests, and production HTTPS
checks for discovery, dynamic registration, PKCE, one-use codes, game tool
discovery and status, rotating refresh, scope isolation, and disconnect
revocation passed. The live check reached 22 tools in its own validation game
and ended only that game. A complete user connection inside the Codex or
Claude host application has not been exercised by this validation.

Validation on 2026-10-01: 742 API tests and 27 console tests passed, together
with an isolated Linux startup and OAuth check. Production HTTPS validation
connected with no active game, discovered the account tools, started a fresh
owned session, discovered its 22 game tools without reconnecting, called the
native game log tool, and ended that session through MCP. The updated consent
screen requires explicit session-control approval; old grants and old consent
pages retain game-only access. End-to-end reconnection inside the user's AI
app still requires that app's normal approval flow.