error.code, then verify the connection path, broker credential,
runtime environment, and trusted provider configuration.
Callback URL mismatch
SetOAUTH_REDIRECT_BASE_URL to the public broker origin and register
/api/connections/callback/{providerId} exactly. Start access again because
pending state retains its original callback.
authorization_superseded
Every unready access intentionally creates a fresh authorization URL and
invalidates older pending state. Open only the most recently returned URL.
connection_configuration_conflict
The path already owns different immutable MCP configuration. Use the original
URL, disconnect the connection before recreating it, or choose a different
namespace.
insufficient_scope
Compare the full path with the broker scopes. Plain scopes are exact;
descendants require an explicit /** suffix.
MCP discovery or registration
Verify protected-resource metadata, authorization-server metadata, and PKCE S256 support. Hookfish prefers HTTPS CIMD when advertised. DCR is only a fallback; a server supporting neither needs fixed client credentials configured on the trustedmcp provider.
Data disappears after restart
Use persistent PGlite storage for local single-process deployments and PostgreSQL for ephemeral or horizontally scaled deployments. Keep the database andOAUTH_ENCRYPTION_KEY together in your recovery plan.
Inspect /api/docs or /api/openapi.json for the exact deployed contract.