Generate a code and connect over MCP

Beshoy Hanna

Beshoy Hanna

— 4 min read
Share

OpenBeam Cloud lets an MCP client work with the game in one of your running sessions. To connect, generate a device approval code, approve it with your OpenBeam account, and exchange it for an access token.

The browser dashboard approves the code. The code is generated by the API or by a client that implements this sign-in flow.

Before you start

You need:

  • An OpenBeam account with Cloud access enabled. See Sign in to OpenBeam Cloud.
  • A terminal with curl for the manual instructions below.
  • An MCP client that supports Streamable HTTP and an Authorization header.

The commands below use a Bash-compatible shell, such as a macOS or Linux terminal or Git Bash on Windows. Replace uppercase placeholders with your own values.

1. Request a new code

Run:

curl -sS -X POST https://cloud.openbeam.world/v1/device/code

No sign-in is needed to request a code. The response contains:

Field How to use it
userCode The eight-character code shown on the approval page, formatted XXXX-XXXX.
deviceCode A private value used to exchange your approval for an access token. Keep it for step 4.
verificationUriComplete The approval link to open in your browser. It already contains your userCode.
verificationUri The base address of the Cloud app. Use verificationUriComplete to open your specific approval request.
expiresIn How long the request remains valid, in seconds. Currently 600 (10 minutes).
interval The minimum delay between token requests, in seconds. Currently 5.

Each call generates a fresh request. If your code expires before you complete the flow, request another code and use the new response's deviceCode and approval link together.

  1. Copy verificationUriComplete from the response and open it in your browser.
  2. If you are signed out, select Sign in with openbeam.world and complete the email sign-in steps.
  3. After sign-in, you should see Sign in on your device? and the code you just requested.

The approval link has this shape:

https://cloud.openbeam.world/app/#device=YOUR_USER_CODE

Use the actual link returned by the API. The Invite code field on the sign-in screen is for beta invitations; the device approval code is displayed separately.

3. Approve the code

Compare the code on the page with userCode from your request. If they match and you initiated the request, select Approve.

The page should confirm approval. If you did not initiate the request, select Deny.

4. Exchange the approval for an access token

Return to the terminal that requested the code. Replace YOUR_PRIVATE_DEVICE_CODE with the original response's deviceCode, then run:

curl -sS https://cloud.openbeam.world/v1/device/token \
  -H 'Content-Type: application/json' \
  -d '{"deviceCode":"YOUR_PRIVATE_DEVICE_CODE"}'

After approval, the response contains userId and token. Save token in your MCP client's credential settings. Keep both deviceCode and the issued token private.

If the response is authorization_pending, finish browser approval and wait at least the returned interval before trying again. If it is slow_down, increase the delay by at least five seconds.

An approval can be exchanged for a token only once. After a successful exchange, use the issued token rather than repeating the exchange. A newly generated code does not revoke an access token issued by an earlier request.

5. Start or identify your session

MCP connects to a specific running simulation. Sign in to the Cloud dashboard with the same account that approved the code, select Play OpenBeam, and keep the browser player open while using MCP.

To find the session ID, replace YOUR_ACCESS_TOKEN with the token from step 4 and run:

curl -sS https://cloud.openbeam.world/v1/sessions \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

The response is a JSON array of your sessions. Choose the sessionId for the running game. Wait for its state to be ready or streaming before connecting. An ended or failed session cannot accept MCP requests.

When you start another session, use its new session ID in your MCP client's URL.

6. Configure your MCP client

Use these settings in your client's remote MCP connection form:

Setting Value
Transport Streamable HTTP
Server URL https://cloud.openbeam.world/v1/sessions/YOUR_SESSION_ID/mcp
Header name Authorization
Header value Bearer YOUR_ACCESS_TOKEN

Replace YOUR_SESSION_ID with the ID from step 5 and YOUR_ACCESS_TOKEN with the token from step 4. The space after Bearer is required.

Your client handles MCP initialization and lists the game's tools once connected. Tool availability depends on the game version running in your session.

Optional: verify the endpoint from a terminal

This request initializes an MCP connection without changing the simulation:

curl -sS -X POST \
  https://cloud.openbeam.world/v1/sessions/YOUR_SESSION_ID/mcp \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example-client","version":"1.0"}}}'

A successful JSON-RPC response includes result.protocolVersion, result.serverInfo, and result.capabilities. Let your MCP client negotiate its own protocol version when connecting normally.

Using the game's existing MCP connection

If your agent is already connected to a running OpenBeam game's MCP server, it can call cloud_sign_in with empty arguments ({}). The game requests the device code and returns user_code and verification_uri_complete.

Open that link and approve the matching code. The game polls for approval and stores its Cloud sign-in automatically; cloud_status reports signed_in once complete. This signs that game into your Cloud account. To connect a separate MCP client to a hosted session, use the session URL and credentials described above.

Troubleshooting

Response or problem What to do
authorization_pending Approve the code in the browser, then retry after at least the returned interval.
slow_down Increase the delay between token requests by at least five seconds.
access_denied The request was denied. Start a new request if you still want to sign in.
expired_token The device code expired, was already exchanged, or is not recognized. If you already received a token, use that token. Otherwise generate a new code.
The approval page says the code expired or was already used Generate a new request and open its new verificationUriComplete link.
401 unauthorized Confirm that you supplied the issued access token with Authorization: Bearer .... If it is no longer accepted, complete a new sign-in flow.
403 not_entitled Check that the approving account has active Cloud access.
403 forbidden Confirm that the session belongs to the account that approved the device.
404 when connecting to MCP Check the complete session URL and session ID.
409 session_not_ready Check that the session is still running and wait for the game to be ready.
405 method_not_allowed The MCP endpoint accepts POST requests. A client may receive 405 when probing GET or DELETE; an HTTP POST connection is required.
429 Too many requests. Wait before retrying. Code generation is limited to 10 requests per minute per IP address.
502 bridge_unreachable or 504 bridge_timeout Check whether the browser game is running, then retry. Contact support if the problem continues.

For account or service help, use the support contact listed on openbeam.world.

Read more