Troubleshooting connections

Most connection problems fall into a handful of cases.

`401 Unauthorized`

The connection isn’t authenticated.

API-key setups — the key is wrong, expired, or revoked. Check you pasted the full oc_live_… value, and that it hasn’t been revoked in World Settings → API Connections. Create a new key if needed.
Connector (sign-in) setups — your access was revoked or the sign-in expired. Reconnect the tool and sign in again. Confirm the app still appears on the portal’s Connected apps page.

`404 Not Found`

The world URL doesn’t resolve. On a single-world connection, check the world ID in the URL — it’s the UUID shown in the portal address bar when you’re inside the world (…/worlds/<world_id>/…). A 404 can also mean the world no longer exists.

Tools are missing

The agent only sees tools its access allows.

Read-only access — write tools (create/update/delete) won’t appear. Use a read-write API key, or check that your role on the world is editor or owner (viewers are read-only).
Connector, no world active — until a world is selected, only the world-listing/switching tools show. Ask the agent to list your worlds and switch to one. See The connector.

The agent can’t switch to a world

On the connector, an agent can only reach worlds you’ve granted that app. If a world is missing or it can’t switch to one you expect:

Add the world to the app on the portal’s Connected apps page (an app can hold up to 32 worlds).
If the world shows a warning there, you no longer have access to it yourself — that has to be restored first.

Rate-limit errors (`429`)

Each plan caps how many MCP requests per minute a user can make against a world. If an agent is making rapid calls, slow it down or move the world to a higher plan.

The connection won’t establish

stdio bridge (mcp-remote) — make sure Node.js 18+ is installed and on your PATH.
Config not picked up — fully quit and reopen the client after editing its config (closing the window often isn’t enough).
Reachability — cloud clients (Claude’s connectors, ChatGPT) reach Orbismo over the public internet; that’s fine for app.orbismo.com, but a locally bridged setup needs the machine running the bridge to have internet access.

Changes aren’t showing in the portal

The portal doesn’t live-update. Refresh the page and the agent’s changes will appear.

Still stuck? Re-check the connection model in How AI integration works.