---
name: mcp-account-brief
description: Connect the Reverse Contact and CRM MCP servers to an AI client and have it research an account and write a pre-call brief onto the CRM record. Use when the user wants agent-driven account research, a pre-call brief, or asks whether MCP can replace an integration build.
---

# Agent-written account briefs

> Generated from https://www.reversecontact.com/integrations-hub/workflows/agent-account-briefs
> Every tier requirement and limit below was read from the vendor's own documentation on 2026-09-18.
> Vendors change these without notice. Re-check anything load-bearing before you rely on it.

**Tools in this workflow:** Reverse Contact, HubSpot, Slack.
**Build effort:** Hours.

## What you are building

Not a pipeline. Two MCP servers connected to an AI client, plus one reusable prompt. The agent reads the CRM, resolves the company and the buying committee, and writes a short brief as a note on the record, where the rep already looks.

## Ask this before writing anything

How many accounts, and on what trigger? One at a time, on demand, driven by a person or a task: this is the right shape. Thousands, on a schedule: this is the wrong shape and you should build the CRM data layer loop instead. An agent exploring an account makes several enrichment calls where a pipeline makes one, so at volume it is slower, less predictable and more expensive.

## Prerequisites

| What | Where to get it | Notes |
|---|---|---|
| Reverse Contact API key or OAuth | Workspace > API Keys | OAuth 2.1 where the client supports it |
| An MCP-capable client | Claude.ai, Claude Desktop, Claude Code, Cowork, ChatGPT, Codex, Cursor, Gemini CLI, or any stdio client via mcp-remote | Remote MCP support is the only requirement |
| The CRM's own connector | HubSpot publishes one for Claude, at 184,000 installs on its marketplace | It runs under your own CRM permissions, so the blast radius is whatever you can do |

## The tools, and how to call them

### Reverse Contact

- **Base:** `https://api.reversecontact.com/v2`
- **Auth:** `Authorization: Bearer rc_your_api_key`. Keys are created in Workspace > API Keys.

| Call | Request | What it does |
|---|---|---|
| `POST /v2/enrich/persons` | `{ "email": "j.okafor@northwind.io" }` | Resolve a person from an email, a name plus company, or a profile URL. Cached resolution, returns in the response. |
| `POST /v2/enrich/companies` | `{ "domain": "northwind.io" }` | Resolve a company from a domain or a name. |
| `POST /v2/fetch/persons` | `{ "linkedInUrl": "..." }` | Standard profile lookup from the database. |
| `POST /v2/fetch/persons/live` | `{ "linkedInUrl": "..." }` | Live on-demand resolution. ASYNCHRONOUS: returns a webhookId to poll, not a record. |
| `POST /v2/search/people` | `{ "filters": { "currentCompanyDomain": "northwind.io" } }` | Filtered people search. 1 credit a profile delivered, and /v2/search/people/count is free. It replaced /v2/search/persons, which returns 410 Gone since 13 October 2026. |
| `POST /v2/search/organizations` | `{ "filters": { "companyDomain": "northwind.io" } }` | Filtered company search. A domain can also go straight to a company through POST /v2/enrich/companies, or through the enrich_company MCP tool since November 2026. |
| `POST /v2/contact/email` | `{ "linkedInUrl": "..." }` | Find an email. ASYNCHRONOUS: returns a taskId to poll. 3 credits for a professional address, 5 for a personal one, 8 for both, refunded when neither is found. |
| `GET /v2/webhooks/:webhookId` | - | Poll an async job until status is "succeeded". Polling is free and does not count against the rate limit. |

Response shape:

```json
{
  "success": true,
  "data": {
    "person": {
      "fullName": "Jane Okafor",
      "headline": "VP Sales at Northwind",
      "location": "London, United Kingdom",
      "linkedInUrl": "https://linkedin.com/in/...",
      "currentPosition": { "title": "VP Sales", "companyName": "Northwind", "startDate": "2023-04" },
      "emails": [], "experience": [], "education": [], "skills": []
    },
    "company": { "name": "Northwind", "domain": "northwind.io",
                 "industry": "Software Development", "employeeCount": 220 }
  },
  "error": null,
  "metadata": { "requestId": "req_...", "executionTimeMs": 480, "updatedAt": "2026-09-01T..." },
  "quotas": { "creditsConsumed": 1, "workspace": { "credits": { "total": 10000, "used": 4521, "left": 5479 } } }
}
```

**Rules that will cost you time if you skip them:**

- A miss returns **null**, not a best guess. Every response carries a confidence score, and you can raise the precision threshold on the request. Branch on it: do not treat a low-confidence answer as a match.
- Use the cached endpoints anywhere that must answer inside one HTTP request. The `/live` endpoints return a task and need polling.
- `quotas.workspace.credits.left` is on every response. Log it, or you will find out about the balance from a 402.
- Credit costs per call are published and a dollar rate per lookup is not: 2 credits for a reverse lookup from an email, 1 for a cached profile lookup, 2 for a live refresh, 3 for a business email and 20 for a direct phone number, with the last two charged only when one is found. Checks and the search count endpoint are free. Credit packs expire after 3 months. Do not hard-code a dollar cost assumption.

**MCP server:** `https://api.reversecontact.com/mcp`

- Auth: OAuth 2.1 where the client supports it, otherwise `Authorization: Bearer rc_your_api_key`.
- Tools: `enrich_person`, `enrich_person_live`, `enrich_company`, `enrich_company_live`, `search_persons`, `search_companies`, `check_usage`, `check_task`
- Streamable HTTP, JSON-RPC 2.0. The `_live` tools return a task id that `check_task` polls.

Docs: https://docs.reversecontact.com/getting-started

### HubSpot

- **Base:** `https://api.hubapi.com`
- **Auth:** `Authorization: Bearer <private-app-token>` for a private app, or OAuth for a marketplace app. Full CRM API access is on every tier including Free.

| Call | Request | What it does |
|---|---|---|
| `PATCH /crm/v3/objects/contacts/{contactId}` | `{ "properties": { "rc_title": "VP Sales" } }` | Update a contact. Send only the properties you own. |
| `POST /crm/v3/objects/contacts/search` | `{ "filterGroups": [...], "properties": [...] }` | Find records by property. Use this to pull the slice that is missing a field. |
| `POST /crm/v3/objects/contacts/batch/update` | `{ "inputs": [ { "id": "...", "properties": {...} } ] }` | Batch of up to 100. Prefer this over per-record PATCH at volume: it is one request against the rate limit. |

**Rules that will cost you time if you skip them:**

- **Rate limits.** A private app gets 190 requests per 10 seconds on Professional and Enterprise, 100 on Free and Starter. Daily caps are 250,000 / 625,000 / 1,000,000 calls **per account, shared across every app**. A public OAuth marketplace app is capped at 110 per 10 seconds per installing account.
- **Calling an external API from a workflow needs Data Hub Professional or Enterprise.** Both the webhook action and the custom code action live in that hub, not in Sales Hub. Check this before designing an in-HubSpot build.
- **Custom code actions get 20 seconds and 128 MB.** Combined length of all workflow secrets is capped at 1,000 characters. Secrets are read with `process.env.NAME`.
- **Workflows:** up to 50 simple on Starter, up to 300 fully customisable on Professional.
- **Never write to a property a human maintains.** Use prefixed properties (`rc_*`) and promote with a separate workflow only where the human field is empty.

**HubSpot custom code action (Node 20):**

```javascript
// Input field: email   Output fields: rc_status, rc_title, rc_company, rc_headcount
// Secret: RC_API_KEY
const axios = require('axios');

exports.main = async (event, callback) => {
  const email = event.inputFields['email'];
  const res = await axios.post(
    'https://api.reversecontact.com/v2/enrich/persons',
    { email },
    { headers: { Authorization: `Bearer ${process.env.RC_API_KEY}` } }
  );

  const person = res.data?.data?.person;
  const company = res.data?.data?.company;

  // null means "not found", not "try harder". Write nothing and flag it.
  if (!person) return callback({ outputFields: { rc_status: 'no_match' } });

  callback({ outputFields: {
    rc_status:    'matched',
    rc_title:     person.currentPosition?.title || '',
    rc_company:   company?.name || '',
    rc_headcount: company?.employeeCount || 0
  }});
};
```

Docs: https://developers.hubspot.com/docs/api/overview

## Build it

### 1. Add both servers

Reverse Contact at its MCP endpoint, and the CRM connector. That is the entire build: no host, no scheduler, no code, nothing to maintain when an API version moves.

### 2. Write the prompt, and include the null clause

This is the part that decides whether the output is useful or confident fiction. The tools return null when they do not know. The model must be told to preserve that. See the prompt below.

### 3. Start on notes, not properties

A note is additive and reviewable. A property write changes a field your routing depends on. Move to property writes only after reading a month of notes and trusting them.

### 4. Check usage after the first week

Call the usage tool. An agent exploring one account may make several enrichment calls. Find out what that actually costs before it becomes a monthly surprise.

### The prompt

```text
Research {company domain} and write a pre-call brief.

1. Use enrich_company for firmographics.
2. Use search_persons for the buying committee: titles matching
   RevOps, Sales Ops, Head of Growth, VP Sales.
3. Read the CRM company record and its open deals, notes and
   last 5 activities.

4. Where a field came back null, write "not found" rather than
   inferring it. Do not estimate headcount, revenue or seniority.
   Say which of the two sources each fact came from.

5. Write the brief as a note on the CRM company record. Under
   200 words. Lead with what changed since the last activity.
```

## Gotchas

- An agent will fill a gap unless told not to. Step 4 of the prompt is not boilerplate caution, it is the difference between a brief a rep can open in front of a prospect and one they cannot.
- Test it on a company you know is thinly covered and check what it says about headcount. That is the fastest way to find out whether the null clause is working.
- The `_live` tools are asynchronous here too: they return a task that the task-check tool polls. Use them only when freshness is the point.
- This does not replace a scheduled two-way sync. It replaces the one-off research task somebody was about to automate badly.

## What breaks, from the vendors' own docs

- **An agent will fill a gap unless told not to.** This is the whole risk and it is entirely addressable in the prompt. Tools that return null are doing the right thing; a model that treats a null as an invitation to estimate is not. Test it by asking for a brief on a company you know is thinly covered and checking what it says about headcount.
- **It writes to your CRM under your permissions.** Which is convenient and means the blast radius is whatever you can do. Start it on notes rather than on properties. A note is additive and reviewable; a property write is a change to a field somebody else depends on.
- **Credits are consumed per call, invisibly.** An agent exploring an account may make several enrichment calls where a pipeline would make one. The usage-check tool exists for exactly this, and it is worth asking for a figure after the first week rather than at the end of the month.
- **The live tools are asynchronous here too.** The live variants return a task that the task-check tool polls. That works fine in an agent loop and it is slower than the cached variants. Use live only when freshness is the reason you are doing this at all.
- **It does not scale to a list.** One account at a time is the shape. If the job is 5,000 accounts on a schedule, that is a pipeline and it belongs in the CRM data layer. Using an agent for that is slower, less predictable and more expensive.

## How to verify it works

- Run it against an account with rich CRM history and confirm the brief leads with what changed rather than restating the firmographics.
- Run it against a thinly covered company and confirm it says "not found" instead of estimating.
- Confirm each fact is attributed to either the CRM or the data API.
- Check that it wrote a note and did not touch any property.
- Call the usage tool and record credits consumed per brief.

## What this costs to run

| Component | Billing | What drives it |
|---|---|---|
| Reverse Contact | Per credit | Every call the agent makes. Usually more per account than a pipeline would make, because an agent explores. |
| HubSpot connector | Free | Published by HubSpot. It runs under your own CRM permissions. |
| AI client | Whatever yours costs | Unchanged by this workflow. No hosting, no scheduler, no instance. |
| Build | Zero | Two connections and a prompt. There is nothing to maintain when an API version moves. |

The variable nobody expects is how many enrichment calls an agent makes while exploring one account. Check your usage after a week rather than guessing, and put a ceiling on it if the answer surprises you.

## Sources

- Reverse Contact: https://docs.reversecontact.com/getting-started
- HubSpot: https://developers.hubspot.com/docs/api/overview
- This workflow, with the reasoning behind each step: https://www.reversecontact.com/integrations-hub/workflows/agent-account-briefs

---

*Published by Reverse Contact, which appears in this directory as a data provider.
No other vendor pays for placement. Where a vendor publishes no public figure, this file says so
rather than estimating. Reverse Contact costs are stated in credits, which it publishes; no dollar
rate per lookup appears here, because none is published and dividing a pack price is not their number.*
