# Set up with a coding agent

> Instructions for an AI coding agent (Claude Code, Codex, Cursor and others) that is helping a person sign up for trackagoat and connect its MCP server.

**Set up trackagoat with your coding agent.** Paste this prompt into Claude Code, Codex, Cursor or another coding agent. Your agent walks you through signing up and connects the MCP server, and never handles your password or API key.

Prompt to paste:

```text
Help me set up trackagoat. trackagoat tracks creators' public TikTok and Instagram posts, works out what each creator is owed from the payout structures I set up, and shows which creators need attention. Its MCP server can read all of that and do the day-to-day work too: add creators and videos, set goals, manage payout structures and record payments. Every record in trackagoat, and each person, has a Markdown document: read the relevant ones before you act, and add what you find.

Read the setup guide first and follow it: https://www.trackagoat.com/docs/agents/setup.md

Rules:
- Don't create accounts, sign in for me or type passwords. Tell me what to open and click, then wait for me.
- Don't ask me to paste an API key into this chat, and never print, log or commit one. If a key is needed, I'll set the TRACKAGOAT_API_KEY environment variable myself.

Steps:

1. Ask whether I already have a trackagoat account. If not, send me to https://www.trackagoat.com/signup (Google, or email and password). After sign-up, trackagoat asks for my name, an organization name and a first project, then offers to add a first creator. Wait until I say I'm signed in.
   Every plan includes MCP and API access. New organizations start on Free, which allows 200 requests a day (each MCP tool call counts as one) and 1 API key. Starter and Ultra raise those limits; to upgrade, I email support@trackagoat.com with my organization name and the plan I want. If a call fails with rate_limit_exceeded, wait the retry_after_seconds it returns before trying again.

2. Connect the trackagoat MCP server: https://www.trackagoat.com/api/mcp (Streamable HTTP). Use sign-in (OAuth) first, because it needs no API key: a trackagoat page opens, I pick the organization and choose "View data", plus "Make changes" if you should be able to change things, such as adding creators, setting goals or recording payouts. Set it up for the client you are running in:
   - Claude Code: run `claude mcp add --transport http trackagoat https://www.trackagoat.com/api/mcp`. Then I run /mcp, choose trackagoat and sign in.
   - Codex CLI: run `codex mcp add trackagoat --url https://www.trackagoat.com/api/mcp`, then `codex mcp login trackagoat`.
   - Cursor: add `"trackagoat": { "url": "https://www.trackagoat.com/api/mcp" }` under "mcpServers" in ~/.cursor/mcp.json. Then I sign in from Cursor's MCP settings.
   - VS Code: add `"trackagoat": { "type": "http", "url": "https://www.trackagoat.com/api/mcp" }` under "servers" in .vscode/mcp.json. Then I start the server and sign in.
   - Claude.ai or Claude Desktop: I add a custom connector with that URL in Settings → Connectors. You cannot do this step.
   Sign-in is the best way for each person to connect their own agent: it identifies them directly, so nobody shares a key. Only if this client can't sign in, use an API key instead. An org admin creates one in trackagoat under Org settings → API keys; the key acts as one member (under "Acts as"), so it should act as me. I set it as TRACKAGOAT_API_KEY. You configure the client to send `Authorization: Bearer <key>`, read from that variable, never written out. The setup guide has the exact config for each client.

3. Check the connection: call the list_projects tool and show me my project names. If the trackagoat tools don't appear yet, ask me to restart this session or reload the client, then try again. Then call get_my_profile to see who you're connected as and whether I already have a personalization document; if I do, follow it.

4. Offer to write my personalization document together, so every future session starts knowing me. It's the Markdown document in trackagoat under Settings → My README, and trackagoat sends it to you at the start of each session. Ask me a few short questions, one or two at a time:
   - who I am and my role;
   - what my job is in running the creator program;
   - the program, creators and goals I care about most;
   - how I most want you to help;
   - preferences: tone, how often to check in, what to look at first, and what you should never do without asking.
   Draft it in Markdown with these headings: About me, My job in the program, What I care about, How to help me, Preferences, Never without asking. Show me the draft, and save it with update_my_readme only after I approve. Everyone in my organization, and their agents, can read it, so leave out anything private. If I say no, move on. Later, when my role or preferences change, offer to update it.

5. Then ask what I want to do first: add creators by TikTok or Instagram handle (add_creator), see how the program is doing (get_program_health), or give a creator a posting goal (create_goal), or set up a payout structure (create_payout_structure).
```

This page is written for the AI agent. It covers sign-up, connecting the [MCP server](https://www.trackagoat.com/docs/agents/mcp.md), checking the connection and a first task. The person does everything that needs a password, a browser sign-in or an API key. The agent runs commands, edits config files and explains each step.

**What trackagoat does:** it tracks creators' public TikTok and Instagram posts for brands and agencies that run creator programs. It calculates what each creator is owed from the program's payout rules and flags creators and posts that need attention.

> **For agents: Rules**
>
> - Never create an account, sign in, or type a password for the person. Tell them what to open and click, then wait for them to confirm.
> - Never ask for an API key in the chat, and never print, log or commit one. A key lives in the `TRACKAGOAT_API_KEY` environment variable or in the client's own secret prompt.
> - Ask before you call a write tool (`add_creator`, `create_goal` and others). Confirm the handles, project and targets first.
> - Get an explicit yes before any tool that can't be undone: `delete_*`, `remove_*`, `void_*`, `archive_*`, `unassign_payout_structure` and `set_accrual_status`. Say what will be lost, and offer the reversible option when the tool's description names one.

## 1. Account and plan

Ask whether the person already has a trackagoat account. If they do, skip to [the plan check](#plan-check).

**Step 1: Send them to sign-up**

Give them [https://www.trackagoat.com/signup](https://www.trackagoat.com/signup). They can sign up with Google, or with email and password. An email sign-up sends a confirmation link first.

**Step 2: Explain the setup steps**

After sign-up, trackagoat asks for:

- their **name**,
- an **organization** name: the workspace, usually the brand or agency,
- a first **project**: a group of creators, such as `Brand ambassadors`,
- optionally, a first **creator** by handle or profile URL. They can skip this; you can add creators later.

If someone invited them to an existing organization, they can accept that invitation instead of creating an organization.

**Step 3: Wait for confirmation**

Wait until they say they're signed in and can see their project.

### Plan check

Every plan includes MCP and API access, so a new organization can connect an agent straight away. Organizations start on **Free**, which allows **200 requests a day** and **1 API key**. Each MCP tool call counts as one request, and the count resets at midnight in the organization's time zone. **Starter** raises the daily limit to 1,000 requests but still allows 1 API key. **Ultra** allows 50,000 requests a day and 5 API keys.

Upgrades are handled by hand: the person emails **support@trackagoat.com** with their organization name and the plan they want. See [Plans and limits](https://www.trackagoat.com/docs/guides/limits.md) for the current numbers. When the daily limit is used up, tool calls fail with `rate_limit_exceeded` until the reset.

## 2. Connect the MCP server

| | |
|---|---|
| **URL** | `https://www.trackagoat.com/api/mcp` |
| **Transport** | Streamable HTTP |
| **Auth** | Sign-in (OAuth 2.1), or `Authorization: Bearer tga_<key>` |

Use sign-in first: there is no key to create or store, and it identifies the person directly, so everyone connects their own agent without sharing a key. When the client starts sign-in, a trackagoat page opens in the browser. The person signs in, picks the **organization**, and chooses **View data** (always on) plus **Make changes** if you should be able to add, change or remove creators, videos, campaigns, goals, payouts and notes. Their role must allow changes. Then they click **Allow access**.

Follow the section for the client you're running in.

### Claude Code

```bash
claude mcp add --transport http trackagoat https://www.trackagoat.com/api/mcp
```

Add `--scope user` to make it available in every project. Then ask the person to run `/mcp` in Claude Code, select **trackagoat** and sign in.

### Codex CLI

```bash
codex mcp add trackagoat --url https://www.trackagoat.com/api/mcp
codex mcp login trackagoat
```

The first command adds `[mcp_servers.trackagoat]` to `~/.codex/config.toml`. The second opens the browser sign-in.

### Cursor

Add this to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (this project only). Merge it into `mcpServers` if the file already exists:

```json
{
  "mcpServers": {
    "trackagoat": {
      "url": "https://www.trackagoat.com/api/mcp"
    }
  }
}
```

Then ask the person to open Cursor's MCP settings and sign in to trackagoat from there. If Cursor doesn't offer a sign-in, use an [API key](#api-key-fallback).

### VS Code

Add this to `.vscode/mcp.json` (merge into `servers` if the file exists):

```json
{
  "servers": {
    "trackagoat": {
      "type": "http",
      "url": "https://www.trackagoat.com/api/mcp"
    }
  }
}
```

Ask the person to start the server (the **Start** action above it in `mcp.json`) and allow the sign-in when VS Code asks.

### Claude.ai and Claude Desktop

An agent can't set this up. Tell the person to open **Settings → Connectors** (on claude.ai: **Customize → Connectors**), choose **Add custom connector**, name it `trackagoat`, enter the URL above, leave the OAuth client fields empty, and click **Connect**. Details: [MCP server](https://www.trackagoat.com/docs/agents/mcp.md#claudeai-and-claude-desktop-custom-connector).

### Other clients

Any client that supports Streamable HTTP and OAuth needs only the URL: it finds the sign-in page from the server's `401` response. For clients that only run local (stdio) servers, see [Stdio-only clients](https://www.trackagoat.com/docs/agents/mcp.md#stdio-only-clients).

### API key fallback

Use an API key when the client can't sign in, for example when it has no OAuth support or sign-in fails with a redirect URI error. Only org admins can create keys. A key acts on behalf of one member and can never do more than they can in the app, so it should act as the person you're helping.

Tell the person to:

1. Open **Org settings → API keys** in trackagoat and click **+ New API key**.
2. Name it after the client and person, for example `Claude Code (Sam)`. Under **Acts as**, pick the person who will use it (the admin, by default).
3. Choose scopes: **Read** is always on. Tick **Write** if you should add creators, videos, goals or notes. Leave **Admin** off.
4. Copy the key. It's shown once.
5. Add `export TRACKAGOAT_API_KEY=<the key>` to their shell profile (for example `~/.zshrc`), then open a new terminal and restart the client. They should not paste the key into the chat.

Check that the variable is set without printing it:

```bash
test -n "$TRACKAGOAT_API_KEY" && echo "TRACKAGOAT_API_KEY is set" || echo "TRACKAGOAT_API_KEY is not set"
```

Then configure the client to read the variable:

**Claude Code**

```bash
claude mcp add --transport http trackagoat https://www.trackagoat.com/api/mcp \
  --header "Authorization: Bearer $TRACKAGOAT_API_KEY"
```

The shell fills in the key, so it never appears in the conversation. Claude Code saves it in its local config. To share the setup through a repo instead, use the `.mcp.json` from the [MCP server page](https://www.trackagoat.com/docs/agents/mcp.md#claude-code), which reads `${TRACKAGOAT_API_KEY}` at startup.

**Codex CLI**

```bash
codex mcp add trackagoat --url https://www.trackagoat.com/api/mcp \
  --bearer-token-env-var TRACKAGOAT_API_KEY
```

Codex reads the variable each time it starts.

**Cursor**

```json
{
  "mcpServers": {
    "trackagoat": {
      "url": "https://www.trackagoat.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:TRACKAGOAT_API_KEY}" }
    }
  }
}
```

**VS Code**

```json
{
  "inputs": [
    { "type": "promptString", "id": "trackagoat-key", "description": "trackagoat API key", "password": true }
  ],
  "servers": {
    "trackagoat": {
      "type": "http",
      "url": "https://www.trackagoat.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:trackagoat-key}" }
    }
  }
}
```

VS Code asks the person for the key when the server first starts and stores it securely, so no environment variable is needed.

## 3. Check the connection

Call `list_projects`. It returns the organization's projects with their `id`, `name` and `readme`. Show the person the project names. Then call `get_my_profile`: it shows who you're connected as and their personalization document. If they have one, follow it.

If the trackagoat tools don't appear, the client loaded its config before you added the server. Ask the person to restart the session or reload the client. In Claude Code, `/mcp` shows each server's status; in Codex, `codex mcp list`.

## 4. Personalization document

Right after setup, offer to write the person's personalization document together, so every future session starts knowing them. It's their **My README** in trackagoat (**Settings → My README**), and the MCP server sends it to their agent at the start of every session. Ask a few short questions, one or two at a time:

1. Who they are and their role.
2. What their job is in running the creator program.
3. The program, creators and goals they care about most.
4. How they most want you to help.
5. Preferences: tone, how often to check in, what to look at first, and what you should never do without asking.

Draft it in Markdown with these headings, show the draft, and save it with `update_my_readme` only after they approve. Pass the `readme_version` from `get_my_profile` as `expected_readme_version`.

```markdown
## About me
## My job in the program
## What I care about
## How to help me
## Preferences
## Never without asking
```

Tell them everyone in their organization, and their agents, can read it, so it shouldn't hold anything private. If they'd rather not, skip it. When their role or preferences change later, offer to update it. A filled-in example is on [Notes and documents](https://www.trackagoat.com/docs/agents/notes.md#suggested-template).

## 5. First tasks

Ask what the person wants to do first. Most tools take a `project_id` from `list_projects`.

| Task | Tool | Notes |
|---|---|---|
| Add creators | `add_creator` | Pass `project_id` and `accounts`, e.g. `[{ "platform": "tiktok", "handle": "name" }]`. One creator can have a TikTok and an Instagram account. This starts a profile and post-discovery update; stats appear once the account's `last_scraped_at` is set. Counts toward the plan's account limit. |
| Track one post | `add_video_by_url` | Pass the post URLs. Counts toward the plan's video limit. |
| See how the program is doing | `get_program_health` | Returns a verdict, KPIs, alerts and creators who stopped posting. A new project has little data until the first updates finish. |
| Give a creator a goal | `create_goal` | For example `metric: "posts"`, `period: "weekly"`, `target_value: 3`. Check progress with `get_goal_compliance`. |
| Write findings down | `update_notes` | Use the default `mode: "append"` so people's notes are kept. Works for every document: creators, videos, campaigns, projects, the organization and payout records. Organization, project and payout documents need an org admin. |
| Read the program's documents | `list_notes`, then `get_notes` | The organization and project documents often hold rules and goals for agents. |
| Group creators into a campaign | `create_campaign`, then `add_to_campaign` | Add creators, videos or other campaigns. Set a view target with `update_campaign` and follow it with `get_campaign_progress`. |
| Set up payouts | `create_payout_structure`, then `assign_payout_structure` | The structure holds the pay rule (flat, goals, CPM, view bonus or per conversion); assigning creators starts their earning. Confirm amounts with the person first. |
| Record a payment | `record_payout_payment` | Records a payment made outside trackagoat and marks the accruals it covers as paid. It doesn't send money. Needs an `idempotency_key`. |

The MCP server covers the whole REST API except organization administration: it can't create or rename projects, invite or remove teammates, manage API keys, or permanently delete conversions and conversion events (it can void and deactivate them). Send the person to the app for those. The full tool list is on the [MCP server page](https://www.trackagoat.com/docs/agents/mcp.md#tools).

## Troubleshooting

| What you see | Cause | Fix |
|---|---|---|
| The server fails to connect, or HTTP `401` | Not signed in yet, the sign-in expired, or the API key is wrong, expired or revoked | Sign in again: `/mcp` in Claude Code, `codex mcp login trackagoat`, or reconnect in Cursor, VS Code or Claude. With a key, check the variable is set (without printing it) and that the key is still listed under **Org settings → API keys**. |
| `insufficient_scope` (`403`) | A write tool was called without **Make changes**, or with a key that lacks **Write** | Reconnect and approve **Make changes**, or have an org admin create a key with **Write**. |
| `insufficient_role` (`403`) | The tool needs an org admin (its description says so), and the person isn't one | Ask an org admin to do it, or to change the person's role. |
| `key_member_removed` or `key_creator_…` (`401`) | The key's member left the org, or the admin who made the key for them left, was changed to member or was suspended | Sign in instead, or have an org admin create a new key. **Org settings → API keys** shows why the old one stopped. |
| The consent page says the plan doesn't include API access | An admin set this organization's API limit to 0 | Pick another organization, or email support@trackagoat.com. See [the plan check](#plan-check). |
| Sign-in shows a redirect URI error | The client uses a custom URL scheme for sign-in, which trackagoat doesn't accept | Use an [API key](#api-key-fallback). |
| `limit_reached` (`402`) | A plan limit, such as the number of tracked accounts or videos | Remove items or upgrade. See [Plans and limits](https://www.trackagoat.com/docs/guides/limits.md). |
| `rate_limit_exceeded` (`429`) | The organization's daily API request limit (it resets at midnight in the org's time zone) or 60 requests per minute per key or connection | Wait `retry_after_seconds`, then retry. Each tool call counts as one request. |
| `retention_exceeded` (`402`) | An analytics range starts before the plan's data-retention window | Use a later start date. |

More detail: [MCP server](https://www.trackagoat.com/docs/agents/mcp.md), [Errors and limits](https://www.trackagoat.com/docs/api-reference/errors.md).

---
Source: https://www.trackagoat.com/docs/agents/setup