> ## Content Index > Fetch the complete content index at: https://openbeam.world/llms.txt > Use this file to discover other available public pages before exploring further. # Generate a code and connect over MCP - URL: https://openbeam.world/docs/generate-a-code-and-connect-over-mcp/ - Published: 2026-09-29T21:48:12.000Z - Updated: 2026-09-29T21:48:12.000Z - Author: Beshoy Hanna - Tags: #docs 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](sign-in.md). - 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: ```bash 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. ## 2\. Open the approval link and sign in 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](sign-in.md#sign-in). 3. After sign-in, you should see **Sign in on your device?** and the code you just requested. The approval link has this shape: ```text 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: ```bash 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: ```bash 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: ```bash 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](https://openbeam.world/).