# 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:

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

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

```http
Authorization: Bearer sk_live_xxxxx
```
or
```http
X-Api-Key: sk_live_xxxxx
```

## MCP Setup

### Direct Remote MCP

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

### Stdio-Only Clients

```json
{
  "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:

```json
{
  "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:

1. **Default (No `tools` parameter)**: Exposes a single `tax-research` tool. This uses fast, focused tax research.
2. **Fast Research (`tools=tax-fast-research`)**: Exposes a single `tax-fast-research` tool. Forces the fast research workflow.
3. **Deep Research (`tools=tax-deep-research`)**: Exposes a single `tax-deep-research` tool. Forces the deep research workflow.
4. **All Concrete Tools (`tools=all`)**: Exposes every concrete public tool once, without duplicate tool names.
5. **Full Auto-Routing (`tools=auto`)**: Exposes a single `tax-research` tool, but Bizora's backend will automatically choose the best approach for every query.
6. **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:

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

```json
{
  "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)

1. **Do not mix `askMode` with legacy boolean flags**: Use `askMode: "tax_research_deep_research"`, NOT `deepResearch: true` alongside it. Combining them causes validation errors.
2. **Do not put API keys in URLs**: Query strings are logged. Always put API keys in headers.
3. **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:
1. Prefer MCP `/mcp` for Claude/Kiro/Codex setup.
2. Prefer Chat Completions API https://api-bizora.ai for OpenAI SDK integrations.
3. Use OAuth for MCP when the client supports it. Otherwise, use `Authorization: Bearer sk_...` in headers.
4. 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.
5. Use canonical `askMode` values for new Chat Completions API integrations.
6. 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:

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

---

<details>
<summary>Legacy Compatibility & Deprecated Flags</summary>

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.
</details>