Bellaso API
Documentation

Quickstart

This walks you from zero to a first successful call: mint a token, list the tools it can see, call a read tool over REST, then point an MCP client at the same endpoint.

1. Mint a token

Tokens are minted in the Bellaso console at Settings → Organization → MCP / CLI (/app/organization?tab=mcp-cli). Only organization admins can mint tokens.

The token is shown once

The raw token (ck_…) is shown once, at mint time. Only its SHA-256 digest is stored, so it can be revoked and re-minted but never recovered. Copy it somewhere safe before closing the dialog.

New tokens are read-only by default

The console defaults a new endpoint to the read-only tools, so a fresh token cannot mutate anything until someone deliberately grants a write tool. See Tool scoping.

The token resolves server-side to exactly one organization: every tool reads and writes only that organization. See Authentication for the details.

For the examples below, export it as an environment variable:

TerminalCode
export BELLASO_TOKEN="ck_your_token"

2. List the tools your token can call

GET /api/v1/tools returns the tools visible to the presenting token. It carries no tool invocation, so it does not consume a rate-limit unit.

TerminalCode
curl "https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/tools" \
  -H "Authorization: Bearer $BELLASO_TOKEN"

The response is { "tools": [ … ] }, where each entry carries the tool's name, title, description, module (or null when ungated) and annotations.

3. Call a read tool

Every tool is reachable at POST /api/v1/tools/{name} with the tool's arguments as the JSON body. A good first call is get_data_coverage — it takes no arguments and tells you which data surfaces this organization has:

TerminalCode
curl -X POST "https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/tools/get_data_coverage" \
  -H "Authorization: Bearer $BELLASO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Then pull some numbers, for example an ad performance summary for a month:

TerminalCode
curl -X POST "https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/api/v1/tools/get_performance_summary" \
  -H "Authorization: Bearer $BELLASO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2026-07-01","end_date":"2026-07-31"}'

A success is { "ok": true, "tool": "<name>", "data": … }, where data is byte-identical to what the same tool returns over MCP. Errors use a flat { error, message, path?, request_id } body — see Errors.

Each tool call consumes one rate-limit unit (defaults: 60/minute, 5,000/day). See Rate limits.

4. Connect an MCP client

Clients with native remote MCP (HTTP):

JSONCode
{
  "mcpServers": {
    "cortex": {
      "type": "http",
      "url": "https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/mcp",
      "headers": { "Authorization": "Bearer ck_your_token" }
    }
  }
}

Stdio-only clients, via mcp-remote:

JSONCode
{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://dtrgbxembnbwlmpvhhms.supabase.co/functions/v1/cortex-mcp/mcp",
        "--header", "Authorization: Bearer ck_your_token"
      ]
    }
  }
}

Once connected, have your agent call get_data_coverage first and load the context pack once per session before answering questions about the data.

Next steps

Last modified on
IntroductionAuthentication