# Agents

> Your AI agent can do in Tellfield what you can, except pay: sign you up, set your market, pick a plan and read every brief. Over MCP or a plain HTTP API, with one key.

## Connect by MCP

The MCP server runs over streamable HTTP at `https://tellfield.com/api/mcp`. Send the key as a Bearer token.

MCP config:

```json
{
  "mcpServers": {
    "tellfield": {
      "type": "http",
      "url": "https://tellfield.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}
```

Claude Code:

```sh
claude mcp add --transport http tellfield https://tellfield.com/api/mcp \
  --header "Authorization: Bearer YOUR_KEY"
```

Without a key the server offers only `sign_up`, `list_plans` and `list_markets`. With one, it offers the tools the key may use. Start with `get_account`: it lists your markets, their plans and where each brief stands.

## Or call the API

The same calls over HTTP, at `https://tellfield.com/api/v1`. Bodies are JSON. The [API reference](https://tellfield.com/docs/api.md) lists every call; the [OpenAPI file](https://tellfield.com/api/v1/openapi.json) describes them for tools.

Latest brief:

```sh
curl https://tellfield.com/api/v1/reports/latest \
  -H "Authorization: Bearer YOUR_KEY"
```

## Keys and what each may do

Make a key for each agent on the Agents page in the app, and tick what it may do. Every key can read. The page shows when each key was last used; revoke one and it stops at once.

| Can | Scope | What it may do | Tools |
| --- | --- | --- | --- |
| No key |  | Sign up its person, list plans and markets. | `sign_up`, `list_plans`, `list_markets` |
| Read | `read` | Read briefs, past and present, the watchlist and the account. | `get_account`, `list_reports`, `get_report`, `get_watchlist` |
| Watchlist | `watchlist` | Set the market, your brand and competitors, and add markets. | `find_company`, `set_watchlist`, `add_market` |
| Plans | `billing` | Pick a plan and get a checkout link for a person to pay. | `start_plan` |
| Keys | `keys` | Make and revoke keys, with no more access than this one. | `list_keys`, `create_key`, `revoke_key` |

A team member's keys can only read; the owner's keys can have any scope. A key with the `keys` scope can make and revoke keys, never with more scopes than its own.

## Sign up your person

An agent without a key can ask for an account for its person, or for a key to the account they already have.

1. Call `sign_up` with their email and your name as they would know it. Add the market, company, competitors and plan you want set up.
2. You get a key at once. It answers `401` with code `confirmation_pending` until they confirm.
3. We email them a link. It shows what you asked for, and they confirm or turn it down. The link works for 24 hours.
4. Once they confirm, the key works. A new account gets its team and market, and its first brief starts. Poll `get_account` about once a minute to see it.

Ask for an account:

```sh
curl https://tellfield.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{
      "email": "marketing@northwind.example",
      "agent_name": "Research assistant",
      "watchlist": {
        "market": "outbound-sales-tools",
        "brand": {
          "website": "northwind.example"
        },
        "competitors": [
          {
            "website": "quillbase.example"
          },
          {
            "website": "fernhill.example"
          }
        ]
      },
      "plan": {
        "tier": "growth",
        "part": "competitors",
        "interval": "month"
      }
    }'
```

Answer (202):

```json
{
  "status": "confirmation_pending",
  "api_key": "tf_…",
  "key_prefix": "tf_r8Kq2mX",
  "scopes": [
    "read",
    "watchlist",
    "billing",
    "keys"
  ],
  "expires_at": "2026-11-13T09:00:00.000Z",
  "next": "We mailed your person a link. …"
}
```

Nothing is made before they confirm: no account, no team, no brief. The answer is the same whether the address has an account or not. For an address that has one, they sign in to confirm, and the key gets no more than their role allows.

> Keep the key safe: it is shown only once. If they turn it down or the link runs out, the key never works; ask again.

## Plans and checkout

Paying always ends with your person. `start_plan` picks a plan for one market and gives you a link to hand them:

| Action | What the link does |
| --- | --- |
| `checkout` | Opens Stripe Checkout. The plan starts once they pay. |
| `confirm` | The market already has a paid plan. The link opens the plan page, where they confirm the change. |
| `saved` | Paying is not open yet. The plan is kept; ask again later for the link. |

Only a key made by the team owner can start a plan.

## Errors

Every error is JSON with `error` (words to show a person) and `code` (to act on). A bad input also has `fields`, with what is wrong with each. Over MCP the same answer comes back as a tool error.

| Status | Code | What to do |
| --- | --- | --- |
| 400 | `bad_request`, `invalid_watchlist` | Fix the input; `fields` says where. |
| 401 | `no_key`, `invalid_key` | Send a working key as `Authorization: Bearer`. |
| 401 | `confirmation_pending` | Wait for your person to confirm, then call again. |
| 401 | `confirmation_declined`, `confirmation_expired` | This key will never work. Ask again with `sign_up`. |
| 403 | `missing_scope` | The key may not do this. `needs` names the scope; ask your person for a key that has it. |
| 403 | `not_in_plan` | This part is not in the plan. The error says which plan has it. |
| 404 | `not_found` | No such week, market or key. |
| 409 | `market_limit`, `same_plan`, `key_limit`, `no_market` | The error says why. |
| 429 | `rate_limited`, `too_many_accounts` | Wait. `Retry-After` says how many seconds. |
| 503 | `checkout_unavailable` | Try again in a few minutes. |

## Limits

| What | Limit |
| --- | --- |
| Calls with a key | 120 a minute per key |
| Calls without a key | 60 a minute per network |
| Sign-ups | 3 a day per email address |
| Watchlist changes | 30 a day per team |
| Websites we read to find a company | 30 an hour per team |
| Keys | 25 per team |
| Markets | 5 per team |