# For agents

If you are an AI agent working for a person: this page says what you can do in Closefinch on your own, what
waits for your principal, what it costs, and how it fails. It's generated from the platform's own tool list.

## Getting in

- **MCP:** `https://api.closefinch.com/mcp` (Streamable HTTP). **REST:** `https://api.closefinch.com/v1`, spec at [https://www.closefinch.com/openapi.json](https://www.closefinch.com/openapi.json).
- **Credentials:** an API key your principal creates in Settings → API keys (`Authorization: Bearer ra_live_…`).
  The key never has more access than the person who made it. Guides per client: [quickstarts](https://www.closefinch.com/docs/quickstart).
- **No key yet?** Create a sandbox: `ra sandbox create --host https://api.closefinch.com` (or `POST /v1/sandbox` with a solved sign-up
  challenge) gives you a sample organization and a limited key at once: CRM and agent scopes, 60 requests a minute, 7
  days, and nothing sent outside until a person claims it.
- **Free plan:** up to 3 seats, 500 AI credits and 5 recording hours a month, no card ([pricing](https://www.closefinch.com/pricing), [pricing.json](https://www.closefinch.com/pricing.json)).

## Two ways in, two sets of rules

- **Your own key's tools** (`ra_records_create`, `ra_records_update`, `ra_records_archive` with `confirm`,
  `ra_activities_create`, `ra_api` and the rest) act at once, with your key's scopes, like a person in the app.
  They're for the edits your principal asked you to make.
- **`ra_propose`** runs one platform tool the way an agent does, through the organization's policy. An MCP request
  counts as outside content, so the strictest rules apply. The lists below are the policy engine's own answer for
  each tool, called this way.

## What runs at once through ra_propose

77 of the 111 platform tools: reads and reasoning inside Closefinch, and writes: new records, notes and
tasks, memory, and notifications to teammates. Some of these writes do reach outside or cost money, and are marked:
they fetch the web on purpose, as their job (refreshing competitors, rebuilding a profile, qualifying accounts, a
paid scrape). Call them only for what your principal asked.

- `account.decide`: Record a decision or next best action for an account
- `canvas.save`: Save a canvas
- `competitors.refresh`: Refresh competitive intelligence (reaches the web)
- `crm.note.create`: Add a note
- `crm.task.create`: Create a task
- `deals.recovery_draft`: File a recovery email for the owner
- `dispatch.page`: Page the on-call technician (notifies a teammate at once)
- `memory.save`: Save a fact to memory
- `notify.person`: Message a teammate (notifies a teammate at once)
- `profile.rebuild`: Rebuild the business profile from your site (reaches the web)
- `proof.mine`: Mine closed-won deals for proof points
- `qualify.accounts`: Qualify accounts against fit questions (reaches the web)
- `recruit.next_batch`: Propose the next design-partner outreach
- `segment.stage`: Stage a segment
- `segments.build_from_icp`: Build segments from the ICP
- `web.scrape_apify`: Scrape with an Apify actor (paid) (reaches the web) (paid per call)
- and these reads: `account.plan`, `activities.search`, `ads.google.query`, `ads.linkedin.report`, `ads.reddit.report`, `analytics.ga4.report`, `background.shared`, `committee.get`, `cpg.account_health`, `cpg.action_list`, `cpg.category_review`, `crm.analyze_write`, `crm.record.get`, `crm.records.search`, `customers.handoff_note`, `deals.review`, `deals.stalled`, `dispatch.triage`, `equipment.account_open`, `equipment.fleet_review`, `forecast.read`, `fundraising.pipeline_review`, `glossary.lookup`, `graph.neighborhood`, `home_services.estimates_review`, `home_services.oncall_review`, `home_services.triage`, `icp.check`, `industrial.rfqs`, `industrial.slow_movers`, `kb.read`, `knowledge.search`, `meetings.brief`, `meetings.followthrough`, `meetings.status`, `memory.list`, `personas.match`, `phones.best`, `phones.list`, `pipeline.stalled_deals`, `prospects.match`, `quotes.get`, `quotes.intel`, `quotes.pipeline`, `relationships.lookup`, `sandbox.run`, `search_console.query`, `signals.list`, `signals.why_now`, `sms.draft_reply`, `tam.overview`, `transcripts.read`, `voice.call_review`, `voice.caller_context`, `voice.campaign_progress`, `voice.catalog`, `voice.find_times`, `voice.payment_status`, `voice.score`, `voice.verify_caller`, `warm.paths`

## What waits for a person

These wait in the approval inbox, and `ra_propose` returns the approval's link for your principal: anything that
reaches outside (web pages, other MCP servers, the browser), sends, and changes to existing records.

- `account.plan.refresh`: Refresh the account plan (changes an existing record)
- `ads.campaign_status`: Pause or enable an ad campaign (sends outside Closefinch) (changes an existing record)
- `agentmail.send`: Send from the agent's mailbox (sends outside Closefinch)
- `browser.act`: Click or type in your browser (sends outside Closefinch) (changes an existing record)
- `browser.extract_table`: Read a table in your browser (reads outside Closefinch)
- `browser.read`: Read a page in your browser (reads outside Closefinch)
- `committee.build`: Map the buying committee (changes an existing record)
- `company.changes`: Hiring, leadership and tech changes for an account (reads outside Closefinch)
- `crm.record.update`: Update a record (changes an existing record)
- `http.get`: Fetch a URL (reads outside Closefinch)
- `http.send`: Send to a URL (sends outside Closefinch)
- `mcp.call`: Act through a connected MCP server (sends outside Closefinch)
- `mcp.read`: Read from a connected MCP server (reads outside Closefinch)
- `media.screenshot`: Screenshot a public web page (sends outside Closefinch)
- `outbound.dnc.add`: Add to the do-not-contact list (changes an existing record)
- `records.account`: Public records for an account (reads outside Closefinch)
- `research.brief`: Research an account or person (reads outside Closefinch)
- `sandbox.run_net`: Run code (allowlisted network) (reads outside Closefinch)
- `segment.append`: Add to a segment (changes an existing record)
- `sms.handoff`: Hand a text thread to a person (changes an existing record)
- `voice.book_meeting`: Book a meeting (sends outside Closefinch)
- `web.read`: Read a web page (reads outside Closefinch)
- `web.scrape`: Scrape structured data from web pages (reads outside Closefinch)
- `web.search`: Search the web or news (reads outside Closefinch)

## Checked per call

These are decided for each call, against facts only the call has (who it reaches, the number's consent and
quiet hours). Without them they're refused:

- `sms.reply`: Answer a text

## For live calls and texts only

These belong to voice agents and the texting desk: they act on the person on a live call or thread, need that call,
and aren't for an MCP agent: `voice.campaign_enroll`, `voice.campaign_result`, `voice.payment_link`, `voice.save_caller`, `voice.send_booking_confirmation`, `voice.send_sms`, `voice.speed_to_lead`, `voice.take_message`, `voice.warm_transfer`.

Approving is never possible through the API or MCP: it happens in the web app or Slack. See
[approvals and policy](https://www.closefinch.com/docs/approvals).

## What it costs

| Unit | Closefinch | Notes |
|---|---|---|
| An API or MCP call | No charge per call | Rate-limited (below) |
| AI work (summaries, drafts, agent runs) | $0.01 per credit (5,000 for $50) | Each run's trace shows its cost; a dry run (`ra_runs_start` with `dry_run: true`) shows the plan first |
| A bot-recorded meeting hour beyond the plan | $1.25 | Imported Zoom, Meet or Teams transcripts use no hours |
| A seat | Team $35, Pro $79 a month, billed annually | Agents aren't seats |

What others publish for the same kind of usage (checked on the date shown, from their own pages):

| Product | Published usage pricing | Checked |
|---|---|---|
| Attio | Credits per seat per month: 100 / 500 / 1,000 / 2,500 by plan. Packs from 5,000 for $70 to 50,000 for $475 (annual). | 2026-11-05 |
| HubSpot Sales Hub | Credits per month: 500 / 3,000 / 5,000 by plan; extra credits $0.01 each. | 2026-11-05 |
| Close | AI credits 500 to 2,000 a month by plan; calls about $0.02 a minute. | 2026-11-05 |
| Day.ai | Flat per agent; Day.ai says it has no usage pricing. Volume discounts. | 2026-11-05 |
| Folk | Email-finder, AI-field and research credits. | 2026-11-05 |
| Lightfield | Pooled workspace credits; extra capture seat $200. | 2026-11-05 |

## Paying

You can't pay, and you don't need to. To suggest a paid plan, call `ra_billing_upgrade_link` (or
`POST /v1/billing/upgrade-link`). It returns a link to the billing page with the plan filled in and tells the
organization's owners. An owner reviews it and pays through checkout, and nothing is bought until then. Machine
payments (x402, agent payment tokens) aren't accepted: a person always pays.

## Limits and errors

- **Rate limit:** per key, published in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Past
  it you get 429 `rate_limited` with `Retry-After` (seconds): wait that long, then retry.
- **Errors** are `{ "error": { "code", "message", "fix", "docs" } }`: the cause, what to do, and a link to its
  section of [the errors page](https://www.closefinch.com/docs/errors).
  - `bad_request` (400): the input didn't validate; `details.issues` lists each field and what's wrong. Fix the
    input and send it again.
  - `unauthorized` (401): no key or a bad one. Ask your principal for a key from Settings → API keys.
  - `forbidden` (403): the key lacks the scope named in the message, or the route is for the web app only.
  - `not_found` (404), `conflict` (409, for example a stale `version`: read the record again), `gone` (410).
  - `policy_blocked` (422): the organization's policy refused it (the kill switch, consent, do-not-contact). Don't
    retry: tell your principal which rule.
  - `unavailable` (503): retry after a short wait.
- Archiving needs `confirm: true`. A merged record answers `moved` (301) with the record it was merged into in
  `Location`: read that one instead.

## A snippet for AGENTS.md, CLAUDE.md or Cursor rules

```markdown
## Closefinch (CRM)
- MCP server: https://api.closefinch.com/mcp with `Authorization: Bearer $RA_API_KEY` (never write the key into a file).
- Start with ra_whoami to see the organization and scopes.
- Read freely. Your key's own tools (ra_records_update, ra_api…) act at once: use them only for what the user asked.
- For sends, outside requests and changes the user didn't ask for, use ra_propose: they wait for a person's approval. Never try to approve.
- On 429, wait Retry-After seconds. On policy_blocked, stop and report the rule to the user.
- Docs: https://www.closefinch.com/docs (every page also as .md); tools: https://www.closefinch.com/docs/mcp/tools.
```