# The MCP server

`apps/track/src/mcp/server.ts` exposes the operator API as MCP tools over
stdio, so running the tracker is a sentence in Claude rather than a
hand-written curl.

Two people running a handful of campaigns do not need a dashboard to type into;
they need to be able to say *"issue links for these thirty handles on the
TripRank campaign"* and have it happen. The work is bulk and irregular, which
suits a conversation better than a form.

It is a thin client over HTTP with no database access, so every rule the API
enforces is enforced here once, not twice. If the API refuses something, so
does this.

## Connecting

```bash
claude mcp add acrune-track --scope user \
  -e ACRUNE_ADMIN_TOKEN=... \
  -e ACRUNE_TRACK_URL=https://track.acrune.com \
  -- npx -y tsx ~/acrune/apps/track/src/mcp/server.ts
```

`ACRUNE_ADMIN_TOKEN` takes an operator key (`acr_admin_…`). It also accepts the
legacy shared token, which still works and is being retired — see
[Accounts and keys](https://acrune.com/dashboard/docs/platform/accounts-and-keys.md).

## Tools

| Tool | What it does |
| --- | --- |
| `list_accounts` | Every client account being tracked |
| `create_account` | Open one. The slug is permanent |
| `list_campaigns` | Campaigns on one account, newest first |
| `create_campaign` | Open one, with its destination and click parameter |
| `issue_links` | Hand a roster one link each. Idempotent on the roster |
| `list_missing_posts` | Every link with no post URL — a campaign's outstanding work |
| `attach_posts` | Attach post URLs in bulk |
| `campaign_performance` | Clicks per post per creator, ranked, optionally windowed |
| `issue_api_key` | A client integration key, with scopes |
| `list_api_keys` / `revoke_api_key` | Manage them |
| `issue_admin_key` | An operator key. Needs `money` |
| `list_admin_keys` / `revoke_admin_key` | Manage them |
| `read_audit_log` | Who did what, newest first, filterable by actor |

`issue_links` is idempotent on the roster, so re-running it after adding a
creator returns the existing links rather than issuing second ones.

## When a call cannot reach the API

A bare `fetch failed` from this server is almost always iCloud Private Relay or
a VPN taking over DNS on the machine running it, rather than the API being
down. The error says so, because that has cost entire evenings before.

```bash
curl -s --resolve track.acrune.com:443:76.76.21.21 https://track.acrune.com/health
```

Answering `{"ok":true}` confirms the API is fine and the local network path is
not.

## This is the operator surface

This server speaks the operator API over stdio, holds an operator
credential, and is global rather than scoped to a tenant. For an agent
working inside one workspace as a person on its team, use the hosted
server instead: see [Agents](https://acrune.com/dashboard/docs/operating/agents.md). A partner integrating a
product uses [the HTTP API](https://acrune.com/dashboard/docs/introduction.md).
