# Bellaso MCP / Agent API

Registry version `8bfe6b0a86d6f539` · **47 tools** (32 read, 15 write).

The Bellaso agent surface lets an organization point its own AI agent — Claude Code, Claude.ai,
an internal agent, any MCP client — or any HTTP client at its Bellaso data. The agent gets
scoped, rate-limited, audited access to that organization's marketing marts and a small set of
low-risk write tools, and nothing else. There is no SQL surface.

There are two doors onto the same pipeline:

- **MCP** (Streamable HTTP, JSON-RPC 2.0) — for AI agents and MCP clients. See
  [Connecting an MCP client](/mcp-clients).
- **REST** — every tool is also callable at `POST /api/v1/tools/{name}`. See
  [Calling the REST twin](/rest) and the interactive [API Reference](/api).

New here? Start with the [Quickstart](/quickstart).

## Endpoints and transport

| Purpose | URL | Method |
|---|---|---|
| MCP (Streamable HTTP) | `https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/mcp` | POST |
| Tool index | `https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/tools` | GET |
| Call a tool | `https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/tools/{name}` | POST |
| This surface's context pack | `https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/context-pack` | GET |
| OpenAPI 3.1 contract (unauthenticated) | `https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/openapi.json` | GET |

The bare function root (`https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp`) also speaks MCP, for clients that will not accept a
path suffix.

- **MCP body:** a single JSON-RPC 2.0 message. Batching (a JSON array body) is **not** supported.
  Bodies are capped at 1 MiB.
- **Notifications** (a message with no `id`, e.g. `notifications/initialized`) get an empty `202`.
- **REST body:** the tool's arguments, as a JSON object. Capped at 64 KiB.
  Every REST response carries an `X-Request-Id` — quote it in support requests and it maps to one
  audit row.
- `serverInfo` reports `{ "name": "cortex-mcp", "version": "1.0.0" }`.

## What's in these docs

| Page | What it covers |
|---|---|
| [Quickstart](/quickstart) | Mint a token, list tools, call a read tool, connect an MCP client |
| [Authentication](/authentication) | The organization-scoped `ck_…` bearer token |
| [Rate limits](/rate-limits) | Per-minute and per-day caps, `Retry-After` |
| [Errors](/errors) | JSON-RPC error codes and REST status codes |
| [Protocol & methods](/protocol) | Supported MCP protocol versions and methods |
| [Tool scoping](/tool-scoping) | The per-endpoint `enabled_tools` allowlist |
| [Auditing](/auditing) | The append-only audit log |
| [Connecting an MCP client](/mcp-clients) | Client configuration for HTTP and stdio-only clients |
| [Calling the REST twin](/rest) | The uniform REST shape and the OpenAPI contract |
| [Context pack](/context-pack) | The agent grounding document |
| [Tools overview](/tools/overview) | All 47 tools, grouped into read and write |
| [API Reference](/api) | Interactive OpenAPI reference and playground |