Agents

Connect by MCP

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

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

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 lists every call; the OpenAPI file describes them for tools.

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.

• No key

  What it may do: Sign up its person, list plans and markets.

  Tools: sign_up, list_plans, list_markets

• Read

  Scope: read

  What it may do: Read briefs, past and present, the watchlist and the account.

  Tools: get_account, list_reports, get_report, get_watchlist

• Watchlist

  Scope: watchlist

  What it may do: Set the market, your brand and competitors, and add markets.

  Tools: find_company, set_watchlist, add_market

• Plans

  Scope: billing

  What it may do: Pick a plan and get a checkout link for a person to pay.

  Tools: start_plan

• Keys

  Scope: keys

  What it may do: Make and revoke keys, with no more access than this one.

  Tools: 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.

curl https://tellfield.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{
      "email": "[email protected]",
      "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"
      }
    }'

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

• checkout

  What the link does: Opens Stripe Checkout. The plan starts once they pay.

• confirm

  What the link does: The market already has a paid plan. The link opens the plan page, where they confirm the change.

• saved

  What the link does: 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.

• 400

  Code: bad_request, invalid_watchlist

  What to do: Fix the input; fields says where.

• 401

  Code: no_key, invalid_key

  What to do: Send a working key as Authorization: Bearer.

• 401

  Code: confirmation_pending

  What to do: Wait for your person to confirm, then call again.

• 401

  Code: confirmation_declined, confirmation_expired

  What to do: This key will never work. Ask again with sign_up.

• 403

  Code: missing_scope

  What to do: The key may not do this. needs names the scope; ask your person for a key that has it.

• 403

  Code: not_in_plan

  What to do: This part is not in the plan. The error says which plan has it.

• 404

  Code: not_found

  What to do: No such week, market or key.

• 409

  Code: market_limit, same_plan, key_limit, no_market

  What to do: The error says why.

• 429

  Code: rate_limited, too_many_accounts

  What to do: Wait. Retry-After says how many seconds.

• 503

  Code: checkout_unavailable

  What to do: Try again in a few minutes.

Limits

• Calls with a key

  Limit: 120 a minute per key

• Calls without a key

  Limit: 60 a minute per network

• Sign-ups

  Limit: 3 a day per email address

• Watchlist changes

  Limit: 30 a day per team

• Websites we read to find a company

  Limit: 30 an hour per team

• Keys

  Limit: 25 per team

• Markets

  Limit: 5 per team