Troubleshooting

The gateway returns structured, specific errors by design. Match what you see:

Connecting clients

Claude says the Waxell Gateway connection expired. Reconnect the connector once. Gateway sessions refresh silently; a reconnect prompt that recurs within a day is a bug — report it with the time it happened.

401 unauthorized with an API key. The key is wrong, revoked, or for another tenant. Keys are tenant-scoped; check which tenant the key belongs to.

Installing & finding tools

Just installed a connector, but find_tools / Connections can't see it. The gateway syncs its upstream registry about once a minute. Wait 60–90 seconds. Persisting after 5 minutes: check the upstream is enabled on the Upstreams page.

Claude's tool list only shows find_tools and call_external_tool. Working as intended — lazy tool exposure. Search with find_tools, dispatch with call_external_tool, or have an admin set scope tags to pre-load upstreams.

find_tools finds nothing for an upstream you installed. Tool inventory comes from fingerprint discovery, which for per-user OAuth upstreams needs at least one connected user. Connect, then My Tools → Refresh.

Connecting accounts

auth_required: <upstream> not connected. Visit … to authorize. You haven't connected your account on this upstream (or you connected as a different user than the one calling). Connections page → Connect.

auth_required: … grant expired and refresh failed; user must re-authorize. The vendor revoked or expired your grant beyond refresh (password change, workspace removal, vendor-side revocation). Reconnect.

MCP OAuth setup failed … no_registration_endpoint. This server speaks MCP OAuth but doesn't accept automatic client registration. An admin must register an OAuth app with the vendor and add the client credentials to the upstream — see Authentication.

MCP OAuth setup failed … dynamic_registration_failed: …. The vendor's registration endpoint rejected the request. The error includes the vendor's reason — capture the full text when reporting.

MCP OAuth setup failed … no_protected_resource_metadata. The URL isn't an MCP-spec-auth server (or isn't an MCP server at all). For a custom upstream, double-check the URL; if the vendor uses classic OAuth, use that mode instead.

Calls failing

Upstream returns invalid_token even though you're connected. Stale grant being served — disconnect and reconnect on the Connections page. Recurring within a day: report it; that pattern points at a refresh bug, not user error.

Tool call blocked/denied … with a rule name. Policy working as configured. The audit row shows exactly which rule fired. Talk to your admin if the rule is wrong.

Call hangs for a while, then proceeds or fails. A require_approval rule parked it for review. The wait is the feature; ask your reviewer, or check the Approvals page.

HTTP 5xx from the gateway itself. Ours. Check status.waxell.dev, report with timestamp and upstream/tool if it persists.

Still stuck?

The audit log (Governance → MCP Gateway → Audit) records every call with its decision and error class — it's the first place to look, and the screenshot to include when you ask for help.