Capabilities

Use this page as operating context for an LLM agent that is helping a customer set up or use Bizora. It describes what the Bizora Chat Completions API and Bizora MCP server can do, what parameters are supported, how responses are shaped, when citations are available, and what the known limits are.

Quick Decision Guide

Connect Claude, Cursor, Kiro, Codex, or another MCP-capable agent: Use Bizora MCP at https://mcp.api-bizora.ai/mcp. The agent gets Bizora tax tools through the Model Context Protocol.
Use an OpenAI SDK or direct HTTP integration: Use the Chat Completions API at https://api-bizora.ai. The API is OpenAI-compatible and supports streaming and non-streaming responses.
Ask tax questions with default speed: Use default tools, tools=tax-fast-research, or askMode: "tax_research_fast_research" for API. This is focused, fast tax research and is the default for platform API keys.
Force deep-research workflow: Use tools=tax-deep-research for MCP or askMode: "tax_research_deep_research" for API when the question needs deeper multi-step research.
Let Bizora pick the best route automatically: Use tools=auto for MCP or askMode: "auto" for API when the agent should not preselect one route.
Need citations/sources in the MCP answer: The default MCP minimal format includes the answer plus sources.s3_file_path and sources.node_id. Use a custom response_format field mask when a client needs more source detail.
Need the full raw supporting payload: Use response_format=full. This is useful for debugging and agent development, but usually too verbose for end users.

Endpoints

Surface	URL
MCP Streamable HTTP	https://mcp.api-bizora.ai/mcp
MCP legacy SSE	https://mcp.api-bizora.ai/sse
Chat Completions API	https://api-bizora.ai

Note: New MCP clients should use /mcp. The /sse route remains available only for older clients that still require HTTP+SSE transport.

Authentication

Get API keys from https://platform.bizora.ai. API keys must start with sk_.

MCP Authentication

The MCP server accepts OAuth bearer tokens. OAuth-capable MCP clients discover Bizora's protected resource metadata at:

https://mcp.api-bizora.ai/.well-known/oauth-protected-resource

OAuth-capable clients should follow the advertised OAuth flow. Customers do not need Auth0 client IDs, secrets, or callback URLs.

For legacy or API-key based MCP clients, pass a Bizora API key as a bearer token header:

Authorization: Bearer sk_live_xxxxx

Do not put API keys in query parameters.

Chat Completions API Authentication

The Chat Completions API accepts either of these headers:

Authorization: Bearer sk_live_xxxxx

X-Api-Key: sk_live_xxxxx

MCP Setup

Direct Remote MCP

{
"mcpServers": {
  "bizora-tax": {
    "url": "https://mcp.api-bizora.ai/mcp"
  }
}
}

Stdio-Only Clients

{
"mcpServers": {
  "bizora-tax": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote@latest",
      "https://mcp.api-bizora.ai/mcp",
      "--transport",
      "http-only"
    ]
  }
}
}

API-Key Header Configuration

Use headers only when the MCP client supports secret headers:

{
"mcpServers": {
  "bizora-tax": {
    "url": "https://mcp.api-bizora.ai/mcp",
    "headers": {
      "Authorization": "Bearer sk_live_xxxxx"
    }
  }
}
}

How MCP Tools Work

Bizora exposes tools based on the tools parameter. Choose the right value based on what you need:

Default (No tools parameter): Exposes a single tax-research tool. This uses fast, focused tax research.
Fast Research (tools=tax-fast-research): Exposes a single tax-fast-research tool. Forces the fast research workflow.
Deep Research (tools=tax-deep-research): Exposes a single tax-deep-research tool. Forces the deep research workflow.
All Concrete Tools (tools=all): Exposes every concrete public tool once, without duplicate tool names.
Full Auto-Routing (tools=auto): Exposes a single tax-research tool, but Bizora's backend will automatically choose the best approach for every query.
Constrained Auto-Routing (e.g., tools=auto,tax-fast-research,tax-deep-research): Exposes a single tax-research tool, but Bizora's backend will only auto-route between the explicitly listed modes.

URL parameter examples:

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=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 returns the answer plus compact source identifiers (sources.s3_file_path and sources.node_id). If a customer expects richer citation data, request additional fields using the response_format parameter.

To get the answer plus richer citation data, use: response_format=answer,sources.sourceOrigin,sources.page_label,sources.text

Available Response Fields

answer: Final generated answer text.
sources: Complete source payloads. You can select specific fields like sources.sourceOrigin, sources.page_label, sources.text, sources.s3_file_path, etc.
steps: Progress or reasoning-step messages.
usage.prompt_tokens, usage.completion_tokens, usage.total_tokens: Token usage information.

If source fields are not present in the response, do not invent citations. Rely on the returned data.

Zero Data Retention (ZDR)

Zero data retention is disabled by default for all MCP and External API calls. The default mode supports standard service operations such as usage analytics, abuse monitoring, reliability, billing, and security. To explicitly enable zero data retention, pass zdr=true (MCP) or ZeroDataRetention: true (API).

When zero data retention is enabled, prompt and response content is not retained for those requests. Some models or providers may be unavailable because they do not support zero data retention. Customers should handle abuse monitoring for zero data retention traffic because Bizora has limited content visibility for those requests.

API example:

{
  "model": "bizora-1.0",
  "messages": [{"role": "human", "content": "Question text"}],
  "ZeroDataRetention": true
}

Any MCP ZDR value other than true or false is invalid.

What You Cannot Do (Known Limitations)

Do not mix askMode with legacy boolean flags: Use askMode: "tax_research_deep_research", NOT deepResearch: true alongside it. Combining them causes validation errors.
Do not put API keys in URLs: Query strings are logged. Always put API keys in headers.
Do not overpromise full citations on default MCP setups: Default minimal includes source identifiers only. Use an explicit response_format field mask when page labels, source text, or other fields are required.

Agent Instructions

When helping a customer:

Prefer MCP /mcp for Claude/Kiro/Codex setup.
Prefer Chat Completions API https://api-bizora.ai for OpenAI SDK integrations.
Use OAuth for MCP when the client supports it. Otherwise, use Authorization: Bearer sk_... in headers.
The default MCP setup returns answer plus sources.s3_file_path and sources.node_id; append ?response_format=answer,sources.sourceOrigin,sources.page_label,sources.text only if the user needs richer source detail.
Use canonical askMode values for new Chat Completions API integrations.
Leave ZeroDataRetention disabled unless the customer explicitly requires zero data retention, and explain the model availability and monitoring tradeoffs before enabling it.

Chat Completions API Contract

Endpoint:

POST /chat/completions

Field	Type	Required	Notes
`messages`	array	yes	OpenAI-style chat messages. The last message is the current user query; all messages are forwarded as context.
`model`	string	no	Must be `bizora-1.0` when provided. Defaults to `bizora-1.0`.
`stream`	boolean	no	`false` by default. `true` returns OpenAI-compatible SSE chunks.
`askMode`	string	no	Canonical mode selector. Preferred over legacy flags.
`allowedAskModes`	array	no	Forwarded when `askMode` is `auto`; used by MCP for constrained auto routing.
`ZeroDataRetention`	boolean	no	Defaults to `false`; set to `true` only when zero data retention is required.

Supported askMode values:

Value	Best for
`tax_research_normal`	Normal first-party webapp tax research.
`tax_research_fast_research`	Fast focused tax research; this is the platform API-key default.
`tax_research_deep_research`	Deep multi-step tax research for complex or high-stakes questions.
`auto`	Backend route selection.

Legacy Compatibility & Deprecated Flags

For older integrations, the following deprecated fields and aliases are still accepted but not recommended for new implementations:

Legacy askMode aliases: normal maps to tax_research_normal, fast_research maps to tax_research_fast_research, and web_search maps to tax_research_web_search.

Legacy boolean flags: websearch: true or webSearch: true maps to tax_research_web_search.

Do not combine askMode with legacy boolean mode flags. Do not set more than one legacy boolean mode flag.

Quick Decision Guide​

Endpoints​

Authentication​

MCP Authentication​

Chat Completions API Authentication​

MCP Setup​

Direct Remote MCP​

Stdio-Only Clients​

API-Key Header Configuration​

How MCP Tools Work​

Citations and Response Formats​

Available Response Fields​

Zero Data Retention (ZDR)​

What You Cannot Do (Known Limitations)​

Agent Instructions​

Chat Completions API Contract​