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

:::warning{title="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.

:::

:::info{title="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](/tool-scoping).

:::

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

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

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

```bash
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`](/tools/read-discovery#get_data_coverage) — it takes no
arguments and tells you which data surfaces this organization has:

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

```bash
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](/errors).

:::tip

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

:::

## 4. Connect an MCP client

Clients with native remote MCP (HTTP):

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

```json
{
  "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`](/tools/read-discovery#get_data_coverage)
first and load the [context pack](/context-pack) once per session before answering questions
about the data.

## Next steps

- [Tools overview](/tools/overview) — every tool and its arguments
- [API Reference](/api) — try the REST endpoints in the interactive playground
- [Errors](/errors) and [Rate limits](/rate-limits)