Troubleshooting

The connector is present but the tool list is empty or missing.

1. Confirm the OAuth flow actually finished. Closing the popup early leaves the connector registered but unauthorized.
2. Start a fresh conversation. Tool lists are attached when a conversation begins, so an existing chat may not pick up a newly connected server.
3. Remove the connector and add it again, at Settings → Connectors. This forces re-registration and a new grant.
4. Check the endpoint is exactly https://opzero.sh/mcp — no trailing slash, no /api prefix.

Access tokens live one hour and refresh silently. If you are being asked to reauthorize constantly, or calls fail with an auth error:

• Run diagnose_auth and read the reported expiry. It is the real expiry from the token record, not an assumption.
• Confirm you are signed in to the OpZero account you expect. The diagnostic reports the identity behind the token — connecting while signed in to a second account is a common and confusing mistake.
• If you signed up recently, verify your email. Accounts are checked at signup and an unverified one cannot deploy.
• Revoking a grant from the dashboard invalidates that client immediately. Reconnect to get a new one.

• Ask for get_deployment_status or get_deployment_logs on the deployment — the status detail usually names the cause outright.
• File paths must be relative, with no leading slash. index.html, not /index.html.
• AI and storage bindings require the default Cloudflare target. They are not available on Netlify or Vercel, and a deploy asking for both will be rejected.
• If you are at a plan cap, creating a new project fails while redeploying an existing one still works. get_system_status shows where you stand, and project_cleanup finds things worth removing.

This is nearly always an exposure-mode problem rather than a broken backend. Claude.ai caches the tool list a gateway advertised when you connected it; an inline gateway changes that list every time its backends change, so the cache and the server drift apart.

Fix it by switching the gateway to search mode, whose meta-tool surface never changes shape:

• Ask for update_gateway with exposure_mode: "search".
• Reconnect the gateway in Claude so it picks up the new surface.
• Changes go live within the gateway’s config cache TTL — about thirty seconds.

Use get_gateway to check per-backend health if individual tools rather than the whole list are missing.

Assistants have no host of their own. They are served from one of your deployed apps’ subdomains, so deploy_assistant succeeds with zero apps deployed but hands back a placeholder rather than a reachable URL.

Deploy any app — deploy_html is enough — and the endpoint materializes at /__oz/assistant/<slug>/chat on that subdomain. To test the assistant before then, use chat_with_assistant, which invokes it server-side and needs no host at all.

Attaching an external connection requires your MCP identity to be linked to your OpZero account. Without the link, the platform can only match your token to your account by an email that was never verified against the grant, which is not a strong enough claim to release a third-party credential.

Run link_identity, open the returned URL in a browser signed in to opzero.sh, and confirm. It is safe to call at any time — with nothing to do, it just reports the links you already have.

A connection showing needs_reauth in list_connections has a stored grant that stopped working. Delete it and create it again.

Ask Claude to call ask_opzero_assistantwith your question — it answers over your account’s actual recent activity, which beats guessing from the outside. For anything else, the concepts page explains most of the behaviour that surprises people.