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.
| Connection | Use it when | URL |
|---|---|---|
| Account MCP | The client asks for one server URL, or you want it to create its own private room | https://freakout.ai/api/mcp/account |
| Room MCP | You are already in a saved Room Editor and want the client to work in that room | copied from Agent access |
| Manual token | The client does not support OAuth for remote MCP servers | copied 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.
Use the account URL when a client has a custom connector screen that only asks for an MCP URL.
Add this server URL in the MCP client:
https://freakout.ai/api/mcp/account
Start the client authentication flow.
Sign in to Freakout if the browser asks.
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.
Review the permission controls.
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.
Use the Room MCP URL when you want the client to work in a specific saved room.
Agent access in the top toolbar.The copied prompt includes the room URL, the MCP server URL, and client-specific command examples. It does not include a secret.
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.
The consent screen controls what the client may do.
| Permission | Allows |
|---|---|
Edit this room | Read room data, preview room drafts, and save room changes |
Agent has write permission | Save changes and create new private rooms |
Allow Agent Spend | Generate 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.
Ask the client to:
room_read first.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.shop_media_list when it needs product images, videos, or existing 3D models.room_preview before saving visual ideas.room_patch or room_upsert only after you approve the direction.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.
Models in immersiveAssets and immersiveProducts use a different physics format from primitive
shapes in scene.geometry. Do not copy physics settings between them.
| Object | Disable physics | Fixed 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.
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.