Troubleshooting
Use this page when Claude, ChatGPT, Cursor, Kiro, or another MCP client cannot connect to Bizora.
Confirm the Endpoint
New clients must use the Streamable HTTP endpoint:
https://mcp.api-bizora.ai/mcp
The legacy /sse endpoint is only for older clients that still require HTTP+SSE transport.
Authentication Fails
OAuth-capable clients discover Bizora's protected-resource metadata at:
https://mcp.api-bizora.ai/.well-known/oauth-protected-resource
If the client uses API keys instead of OAuth, pass the key as a bearer token header. Do not put API keys in query parameters.
Authorization: Bearer sk_live_xxxxx
No Sources or Citations
MCP minimal responses include answer plus compact source identifiers by default:
sources.s3_file_path
sources.node_id
If a client needs richer citation fields, such as page labels, source origins, or source text, add this response format:
response_format=answer,sources.sourceOrigin,sources.page_label,sources.text
If requested source fields are absent, the client must not invent citations. Retry with response_format=full when debugging the source payload.
Tools Look Wrong
The default setup exposes tax-research, backed by tax_research_fast_research.
Supported selectors are tax-research, tax-fast-research, tax-deep-research, audit-research, all, and auto. URL parameters take precedence over X-Tools and X-Include-Tools headers.
Do not combine tools=all with tools=auto.
Invalid ZDR Value
Zero data retention is disabled by default. If you set ZDR explicitly, only true and false are valid values. Passing any other value returns an error.
zdr=invalid_value
Request Times Out
Tax research queries can take 60+ seconds. Bizora sends MCP progress notifications every 5 seconds when the client supplies a progressToken.
Use a client that respects progress notifications or allows longer-running MCP tool calls.
Claude Desktop Config Warning
If Claude Desktop shows Some MCP servers could not be loaded and mentions claude_desktop_config.json, the local JSON config is invalid or not a valid MCP server configuration.
Use the Custom Connector guide for remote custom setup. It connects directly to https://mcp.api-bizora.ai/mcp and avoids local Desktop JSON setup.