Freakout AIFreakout AI

Connect an MCP Client

Use MCP to let Claude, Codex, or another MCP client inspect a room, preview edits, save approved

changes, create private rooms, and generate assets inside a credit limit you approve.

Choose a Connection#

ConnectionUse it whenURL
Account MCPThe client asks for one server URL, or you want it to create its own private roomhttps://freakout.ai/api/mcp/account
Room MCPYou are already in a saved Room Editor and want the client to work in that roomcopied from Agent access
Manual tokenThe client does not support OAuth for remote MCP serverscopied from Agent access

OAuth connections are preferred. The prompt contains no token; your MCP client signs in through the browser and stores the tokens itself.

Account MCP#

Use the account URL when a client has a custom connector screen that only asks for an MCP URL.

  1. Add this server URL in the MCP client:

    https://freakout.ai/api/mcp/account
    
  2. Start the client authentication flow.

  3. Sign in to Freakout if the browser asks.

  4. Choose an existing connected shop, including Shopify. If none is connected, choose Connect Shopify to connect it in a new tab, then return and select Refresh shops. If you do not use Shopify, choose Basic account.

  5. Review the permission controls.

  6. Select Allow.

Selecting Basic account turns on the write-permission switch by default. You can turn it off before approving. Allow creates your first shop from your account details. No shop is created before approval, and an account with a connected shop cannot create an extra one here. Freakout then creates a private workspace room for that client and shop. Reconnecting the same client in the same shop returns it to that room when the connection is still valid.

Room MCP#

Use the Room MCP URL when you want the client to work in a specific saved room.

  1. Open the saved room in the Room Editor.
  2. Select Agent access in the top toolbar.
  3. Copy the setup prompt.
  4. Paste the prompt into the MCP client.
  5. If the client is not configured yet, run the command shown in the prompt.
  6. Authenticate the server from the client.
  7. Approve the browser request in the Room Editor.
  8. Ask the client to read the room before it changes anything.

The copied prompt includes the room URL, the MCP server URL, and client-specific command examples. It does not include a secret.

Client Commands#

Use the room-specific server name and URL from the copied prompt.

claude mcp add --transport http freakout-room-abc123 https://freakout.ai/api/mcp/rooms/<roomId>
codex mcp add freakout-room-abc123 --url https://freakout.ai/api/mcp/rooms/<roomId>
codex mcp login freakout-room-abc123

In Claude Code, use /mcp, choose the Freakout server, then select Authenticate.

Permissions#

The consent screen controls what the client may do.

PermissionAllows
Edit this roomRead room data, preview room drafts, and save room changes
Agent has write permissionSave changes and create new private rooms
Allow Agent SpendGenerate images and 3D assets within the selected credit limit

Generation uses the approved connection budget. The client can read quotes before spending, and it cannot buy credits, change subscriptions, or publish a room.

Working With the Client#

Ask the client to:

  • Call room_read first.
  • Use room_list to see which rooms the connection can work in and which one is active. The list covers the room you connected plus rooms the client created. Rooms that already existed in the shop are not included.
  • Use shop_media_list when it needs product images, videos, or existing 3D models.
  • Use room_preview before saving visual ideas.
  • Save with room_patch or room_upsert only after you approve the direction.
  • Use the latest updatedAt value when saving.

Keep the Room Editor open while reviewing preview drafts. If you have unsaved local edits, Freakout will not silently replace them with agent changes.

Physics settings for models and geometry#

Models in immersiveAssets and immersiveProducts use a different physics format from primitive shapes in scene.geometry. Do not copy physics settings between them.

ObjectDisable physicsFixed collision body
Model asset or product{"enabled":false}{"enabled":true,"type":"fixed"}
Primitive geometry{"bodyType":"none"}{"bodyType":"fixed"}

For model assets and products, physics.bodyType is unsupported by the save format, even if the MCP capability schema accepts it. Use physics.enabled and physics.type instead.

A successful preview confirms that the editor received the draft; it does not prove the draft can be saved. After an approved save, call room_read and check that the intended objects persisted before reporting success. If saving fails, preserve the draft and correct its fields; do not regenerate paid assets.

Disconnect#

Open Agent access in the Room Editor and disconnect the active agent connection. The current access token stops working immediately and refreshes fail.

An account connection can cover multiple shops selected on the approval screen. Each selected shop gets a private workspace. Ask the agent to call room_list to find the workspace and its shop, then pass its roomId when working there. New rooms can target an approved shopHost. Unselected shops remain inaccessible and the generation allowance is shared across the connection. To add shops, reconnect and approve the updated selection.

Freakout approval screens show the Freakout logo and a link back to your shops. Errors and expired requests stay on the branded approval screen. After approval, the browser returns to the MCP client; that client controls its callback page and may close it automatically.