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, or another MCP-capable agent: Use Bizora MCP at https://mcp-dev.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://dev.api-bizora.ai. The API is OpenAI-compatible and supports streaming and non-streaming responses.
Ask tax questions with default speed: Use default tools for MCP or askMode: "tax_research_fast_research" for API. This is focused, fast tax research and is the default for platform API keys.
Force web/current-information lookup: Use tools=tax-web-search for MCP or askMode: "tax_research_web_search" for API when the answer may depend on current web information.
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: Use response_format=answer,sources.sourceOrigin,sources.page_label,sources.text. The default MCP format is answer-only, so sources must be explicitly requested.
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-dev.api-bizora.ai/mcp
MCP legacy SSE	https://mcp-dev.api-bizora.ai/sse
Chat Completions API	https://dev.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-dev.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-dev.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-dev.api-bizora.ai/mcp"
  }
}
}

Stdio-Only Clients

{
"mcpServers": {
  "bizora-tax": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote@latest",
      "https://mcp-dev.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-dev.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.
Web Search (tools=tax-web-search): Exposes a single tax-web-search tool. Forces a lookup using current web information.
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 (fast research, web search, etc.) for every query.
Constrained Auto-Routing (e.g., tools=auto,tax-fast-research,tax-web-search): Exposes a single tax-research tool, but Bizora's backend will only auto-route between the explicitly listed modes.

URL parameter examples:

https://mcp-dev.api-bizora.ai/mcp?tools=tax-web-search
https://mcp-dev.api-bizora.ai/mcp?tools=all
https://mcp-dev.api-bizora.ai/mcp?tools=auto
https://mcp-dev.api-bizora.ai/mcp?tools=auto,tax-fast-research,tax-web-search

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

CRITICAL: By default, Bizora MCP returns ONLY the text answer. Citations are OFF by default. If a customer expects citations or sources, you MUST explicitly request them using the response_format parameter.

To get the answer plus essential 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 enabled by default for all MCP and External API calls. Bizora will not retain customer data. To explicitly disable it (if a customer allows retention), pass zdr=false (MCP) or ZeroDataRetention: false (API).

API example:

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

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_web_search", NOT websearch: true. Combining them causes validation errors.
Do not put API keys in URLs: Query strings are logged. Always put API keys in headers.
Do not promise citations on default MCP setups: Unless response_format includes sources, the API will not return them.

Agent Instructions

When helping a customer:

Prefer MCP /mcp for Claude/Cursor/Kiro setup.
Prefer Chat Completions API https://dev.api-bizora.ai for OpenAI SDK integrations.
Use OAuth for MCP when the client supports it. Otherwise, use Authorization: Bearer sk_... in headers.
Always append ?response_format=answer,sources.sourceOrigin,sources.page_label,sources.text for MCP setups if the user wants sources/citations.
Use canonical askMode values for new Chat Completions API integrations.
Keep ZeroDataRetention enabled unless instructed otherwise.

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 `true`; set to `false` only when retention is allowed.

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_web_search`	Web/current-information tax research.
`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​