# Troubleshooting

Use this page when Claude, Cursor, Kiro, Codex, or another MCP client cannot connect to Bizora.

## Confirm the Endpoint

New clients must use the Streamable HTTP endpoint:

```txt
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:

```txt
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.

```http
Authorization: Bearer sk_live_xxxxx
```

## No Sources or Citations

MCP `minimal` responses include `answer` plus compact source identifiers by default:

```txt
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:

```txt
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`, `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.

```txt
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 [Claude remote connector guide](./apps/claude.mdx) for the recommended setup. It connects directly to https://mcp.api-bizora.ai/mcp and avoids local Desktop JSON setup.