# MCP Integrations Use Bizora's tax research capabilities directly in Claude, Cursor, Kiro, Codex, or any MCP-compatible client. For setup in specific apps, see [Claude](./apps/claude.mdx), [Kiro](./apps/kiro.mdx), or [Codex](./apps/codex.mdx). For the complete LLM-agent-facing contract, see [Capabilities](../capabilities.mdx). ## Endpoint Use the Streamable HTTP endpoint for new clients: ```txt https://mcp.api-bizora.ai/mcp ``` *Note: The legacy `/sse` endpoint remains available for older clients, but new setups must use `/mcp`.* ## Configuration ### Prerequisites - API key from https://platform.bizora.ai for API-key based clients. - An MCP-compatible client. ### Direct Remote MCP Use this when your client supports remote MCP servers: ```json { "mcpServers": { "bizora-tax": { "url": "https://mcp.api-bizora.ai/mcp" } } } ``` OAuth-capable clients can discover the Bizora OAuth flow automatically. They do not need Auth0 client IDs, secrets, or callback URLs. ### API-Key Header Configuration Passing credentials and options via HTTP headers is the recommended approach for clients that support headers. **Why headers?** 1. **Security**: Query strings are often logged by web proxies and gateways. Putting your API key in the `Authorization` header keeps it secure. 2. **Cleanliness**: It avoids cluttering connection URLs with complex options. Here is the recommended configuration file block containing both authentication and configuration options as headers: ```json { "mcpServers": { "bizora-tax": { "url": "https://mcp.api-bizora.ai/mcp", "headers": { "Authorization": "Bearer sk_live_YOUR_API_KEY", "X-Tools": "auto" } } } } ``` *Note: Never put your API key in query parameters.* ### Stdio-Only Clients For clients that do not support remote transport directly, use `mcp-remote`: ```json { "mcpServers": { "bizora-tax": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://mcp.api-bizora.ai/mcp", "--transport", "http-only" ] } } } ``` ## How MCP Tools Work Bizora exposes tools based on the `tools` parameter in the URL. Choose the right value based on your needs: | Selector | Exposed tool | Backend route | Best for | |---|---|---|---| | omitted | `tax-research` | `tax_research_fast_research` | Default focused tax research. | | `tax-research` | `tax-research` | `tax_research_fast_research` | Same as default. | | `tax-fast-research` | `tax-fast-research` | `tax_research_fast_research` | Explicit fast research. | | `tax-deep-research` | `tax-deep-research` | `tax_research_deep_research` | Explicit deep research. | | `audit-research` | `audit-research` | `audit_research` | Explicit audit research. | | `all` | all concrete tools | explicit per-tool route | Expose every concrete public tool once. | | `auto` | a single generic tool | `auto` | Let Bizora choose the best route for every query across all supported domains. | | `auto,tax-fast-research,tax-deep-research` | a single generic tool | constrained `auto` | Let Bizora choose between explicitly selected routes. | Pass selectors in the URL when possible: ```txt https://mcp.api-bizora.ai/mcp?tools=tax-fast-research https://mcp.api-bizora.ai/mcp?tools=tax-deep-research https://mcp.api-bizora.ai/mcp?tools=audit-research https://mcp.api-bizora.ai/mcp?tools=all https://mcp.api-bizora.ai/mcp?tools=auto https://mcp.api-bizora.ai/mcp?tools=auto,tax-fast-research,tax-deep-research ``` Header alternatives are `X-Tools` and `X-Include-Tools`. URL parameters take precedence over headers. Do not combine `tools=all` with `tools=auto`; `all` exposes separate tools while `auto` exposes one auto-routing tool. ## Citations and Response Formats By default, Bizora MCP uses the `minimal` response format and returns a compact JSON payload with the final `answer` and source identifiers for citation mapping: ```json { "answer": "Final answer text...", "sources": [ { "s3_file_path": "s3://...", "node_id": "..." } ] } ``` Use a custom response format only when the client needs richer source metadata such as page labels, source origins, or source text: ```txt https://mcp.api-bizora.ai/mcp?response_format=answer,sources.sourceOrigin,sources.page_label,sources.text ``` If requested source fields are absent, the AI should not invent citations. Retry with `response_format=full` when debugging the source payload. ### Other Response Formats You can request usage, progress steps, or the full structured response: ```txt https://mcp.api-bizora.ai/mcp?response_format=full https://mcp.api-bizora.ai/mcp?response_format=answer,usage https://mcp.api-bizora.ai/mcp?response_format=answer,steps ``` Top-level fields are `answer`, `usage`, `sources`, and `steps`. Usage fields can be selected with `usage.prompt_tokens`, `usage.completion_tokens`, and `usage.total_tokens`. ### Structured Response Skeleton With `response_format=full` or `X-Response-Format: full`, MCP returns this structure: ```json { "answer": "AI-generated answer text", "usage": { "prompt_tokens": 120, "completion_tokens": 650, "total_tokens": 770 }, "sources": [ { "type": "source_message", "content": [ { "s3_file_path": "s3://...", "node_id": "...", "page_label": 1, "sourceOrigin": "https://...", "metadata": { "sourceOrigin": "https://..." }, "text": "Source excerpt..." } ], "request_id": "thread_..." } ], "steps": [ { "type": "step_message", "title": "Processing Query", "description": "Research step description", "request_id": "thread_..." } ] } ``` The fields inside each `sources[].content[]` item vary by source type. The example shows common fields; unavailable fields are omitted. Source item fields can be selected with paths such as `sources.sourceOrigin`, `sources.s3_file_path`, `sources.page_label`, `sources.metadata`, `sources.text`, `sources.tool`, `sources.citation_label`, and `sources.node_id`. Default `minimal` includes only `sources.s3_file_path` and `sources.node_id`. If a selected field is missing, that field is omitted for that source item. If you request both `sources` and nested source fields, `sources` wins and returns the complete source payload. ## Zero Data Retention Zero data retention is disabled by default for MCP requests. The default mode supports standard service operations such as usage analytics, abuse monitoring, reliability, billing, and security. To explicitly enable zero data retention, pass `true`: ```txt https://mcp.api-bizora.ai/mcp?zdr=true ``` For clients that support custom headers: ```json { "mcpServers": { "bizora-tax": { "url": "https://mcp.api-bizora.ai/mcp", "headers": { "Authorization": "Bearer sk_live_YOUR_API_KEY", "X-Zero-Data-Retention": "true" } } } } ``` When zero data retention is enabled, prompt and response content is not retained for that connection. Some models or providers may be unavailable because they do not support zero data retention. You should handle abuse monitoring for zero data retention traffic because Bizora has limited content visibility for those requests. Only `true` and `false` are valid values. ## Capabilities Resource The MCP server exposes the customer-facing capabilities guide as a standard MCP resource: ```txt bizora://docs/capabilities ``` Clients that support MCP resources can read this resource to understand available tools, setup parameters, citation behavior, response formats, and known limitations. ## Authentication Details OAuth-capable clients discover Bizora's protected-resource metadata from: ```txt https://mcp.api-bizora.ai/.well-known/oauth-protected-resource ``` For API-key based clients: ```http Authorization: Bearer sk_live_xxxxx ``` API keys must start with the `sk_` prefix. Get your key from https://platform.bizora.ai. ## Long-Running Requests Tax research queries can take 60+ seconds. The server sends MCP progress notifications every 5 seconds when the client supplies a `progressToken`. Clients must support progress-based timeout reset for those notifications to prevent request timeouts.