Health, errors & troubleshooting

Health check

The /health endpoint is public (no token) and reports dependency status:


curl -s "https://mcp.bonafide.ai/health"


{
  "status": "healthy",          // "healthy" | "degraded"
  "mongodb": { "connected": true },
  "redis":   { "connected": true },
  "uptime_seconds": 12345
}

Error envelope

Errors are returned as a JSON object with a typed code and a human-readable message:


{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

HTTP	code	When
400	`bad_request`	Malformed request — e.g. a non-`initialize` call missing the `mcp-session-id` header.
401	`unauthorized`	Missing, malformed, or expired bearer token; audience/issuer mismatch; or a valid token whose `client_id` has no provisioned organization scope. Carries a `WWW-Authenticate` header pointing at the protected-resource metadata.
404	`not_found`	Unknown route or resource.
429	`rate_limited`	Rate limit exceeded; may include a `retry_after` field. Back off and retry.
500	`internal_error`	Unexpected server error. Retry with backoff; if persistent, open a ticket (see Contact & escalation).

Troubleshooting

Symptom	Likely cause & fix
`401 unauthorized` on `/v1/sse` with a fresh token	Token expired, or the wrong Keycloak realm/audience. Re-mint the token (see Connect programmatically) and confirm you used the production issuer `uauth.bonafide.ai`.
`401 unauthorized` but the token verifies fine	Your `client_id` has no organization scope provisioned yet. Contact Bonafide to confirm your organization scope is attached to your key.
`400 bad_request` after a successful `initialize`	You omitted the `mcp-session-id` header. Every call after `initialize` must echo the session id from the `initialize` response header.
Empty results from `bonafide_query`	Rephrase with the explicit hotel/brand name (use the property’s full registered name, not a colloquial nickname), and confirm the entity is within your scope.
Connector won’t authorize in a non-Claude.ai client	The OAuth redirect is allow-listed to `https://claude.ai/`. Use the bearer-token path (see Connect programmatically), or ask Bonafide to allow-list your redirect URI.
`/health` shows `"redis": { "connected": false }`	A transient dependency issue on the Bonafide side — retry shortly and, if it persists, open a ticket (see Contact & escalation).