Troubleshooting

Common issues and their fixes. Most are deliberate safety behaviour rather than bugs.

A backend on localhost/private IP is rejected

SSRF protection blocks loopback and private addresses by design. For local development only, set ALLOW_PRIVATE_IPS=true to register backends at 127.0.0.1 etc. Never enable it in production.

Admin login fails over http://localhost

The session cookie is __Host-/Secure by default and browsers won't store it over plain HTTP. For local dev, set SESSION_COOKIE_SECURE=false and NODE_ENV=development (which relaxes the startup guard). In production, serve over HTTPS and leave both at their defaults.

Login was working, now the cookie won't set on localhost

Toggling SESSION_COOKIE_SECURE on the same origin can leave a stale __Host- cookie that shadows the plain one. Clear the site's cookies and log in again.

A sharded/bundle endpoint returns 404 for my session

The per-client and bundle endpoints reject a session created for a different scope, and return the same 404 as an unknown session (so a caller can't distinguish "wrong shard" from "no session"). Open the session against the exact URL you'll use.

Discovery finds no tools / errors

• No tools — check your include_tags / exclude_operations filters aren't excluding everything.
• OPENAPI_CYCLIC_REFERENCE — the spec has a self-referential cycle (often a YAML anchor loop); the bridge rejects it rather than hang. Flatten the offending schema.

Tool calls are rejected

• Allowed-key restriction — the calling key isn't in the tool's allow-list (fail-closed even if global auth is off).
• Guardrail — the input matched a deny-rule or secret pattern, or the key lacks elevated scope for a sensitive tool.
• Circuit breaker open — the backend is failing; calls fail fast until it recovers.

I missed the first-run admin credentials

On a boot with BOOTSTRAP_ADMIN_USERNAME/_PASSWORD unset and an empty users table, the gateway generates an admin account and prints its password once to stdout. Only the argon2id hash is stored, so it cannot be reprinted — and setting BOOTSTRAP_ADMIN_* afterwards is ignored, because an admin user now exists.

Look in the boot output first (docker logs <container>, docker compose logs mcp-bridge, kubectl logs deploy/<release>) — the banner is a ruled block, not a log line. If it is truly gone, either set ADMIN_API_KEYS and create a replacement admin over POST /admin-api/users with that Bearer, or delete the unused admin row so the next boot generates a fresh credential. Both paths, and the warning the gateway repeats until that account first signs in — or until you set ADMIN_API_KEYS, which is why it can stop without a sign-in — are in First-run admin credentials →.

The admin UI isn't served

The backend serves the built SPA from admin-ui/dist at /admin. If you see a warning that admin-ui/dist is missing, run bun run build in admin-ui/ (the Docker image does this in a dedicated stage).

Still stuck?

Open an issue with the request ID from the error response (error.request_id) — it ties the failure to the structured server log.