Connect AI agents (MCP)
Set up the Reverse Contact MCP server in Claude, ChatGPT, Codex or Cursor to enrich profiles, search people and companies, and find emails.
What is MCP
The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools directly. Once connected, your AI agent can enrich profiles, search people and companies, find email addresses and phone numbers, keep people in Lists and enrich files in bulk when you ask in plain language.
Reverse Contact exposes 37 tools via MCP, with the same data, credits and rate limits as the REST API.
Prerequisites
- A Reverse Contact account
- An MCP-compatible client (claude.ai, Cowork, Claude Desktop, Claude Code, ChatGPT, Codex, Cursor, etc.)
Two ways to authenticate:
- Sign in with your account (OAuth): clients with OAuth support (claude.ai, Cowork, Claude Desktop, Claude Code, mobile, ChatGPT) connect with no API key. The first connection opens your browser, you approve the access, and a dedicated API key named
MCP - {app}is created in your workspace automatically. - API key: every other client authenticates with an active API key (
rc_*) in theAuthorizationheader. Create one from API Keys.
Server details
| Property | Value |
|---|---|
| URL | https://api.reversecontact.com/mcp |
| Transport | Streamable HTTP (POST only) |
| Authentication | OAuth 2.1 (sign in) or Authorization: Bearer rc_your_api_key |
| Protocol | JSON-RPC 2.0 |
Setup by client
For clients using an API key, replace rc_your_api_key with your actual key in the examples below.
Claude.ai, Claude Desktop, Cowork and mobile
Reverse Contact is published in the Claude connector directory, so there is nothing to paste and no API key involved:
- Open our page in the Claude connector directory.
- Click Connect: your browser opens the Reverse Contact consent page. Sign in if needed, pick the workspace shown, and approve.
The connector is then available in claude.ai chats, Claude Desktop, Cowork, Claude Code on the web and the mobile apps. To revoke it later, delete its MCP - {app} key from API Keys.
To add it by hand, for example when your organization restricts the directory, open Settings > Connectors > Add custom connector, paste https://api.reversecontact.com/mcp as the URL, confirm, then click Connect and approve the same consent page.
Claude Code
Claude Code supports HTTP MCP servers natively. Add Reverse Contact with one command in your terminal, no API key needed:
Terminal
claude mcp add --transport http reversecontact https://api.reversecontact.com/mcpThen start a Claude Code session and run /mcp: select reversecontact and authenticate. Your browser opens the consent page, you approve, and the tools come online.
For headless or CI environments where the browser flow is not an option, pass an API key explicitly instead:
Terminal
claude mcp add --transport http reversecontact \
https://api.reversecontact.com/mcp \
--header "Authorization: Bearer rc_your_api_key"Alternatively, add a .mcp.json file at the root of your project to share the server with your team:
.mcp.json
{
"mcpServers": {
"reversecontact": {
"type": "http",
"url": "https://api.reversecontact.com/mcp",
"headers": {
"Authorization": "Bearer rc_your_api_key"
}
}
}
}ChatGPT
Reverse Contact is published in the ChatGPT plugin directory, so there is nothing to paste and no API key involved:
- Open our page in the ChatGPT plugin directory.
- Click Add: your browser opens the Reverse Contact consent page. Sign in if needed, pick the workspace shown, and approve.
The connector is then available in ChatGPT. Enable it from the composer (plus menu) in any chat. To revoke it later, delete its MCP - {app} key from API Keys.
To add it by hand, for example when your organization restricts the directory, enable Developer mode under Settings > Connectors > Advanced settings (paid ChatGPT plan: Plus, Pro, Business, Enterprise or Edu), then click Create to add a connector: name it Reverse Contact, paste https://api.reversecontact.com/mcp as the URL, keep Authentication on OAuth, and approve the same consent page.
Codex
The Codex CLI reads the bearer token from an environment variable, so the key never lands in a config file:
Terminal
export RC_API_KEY="rc_your_api_key"
codex mcp add reversecontact \
--url https://api.reversecontact.com/mcp \
--bearer-token-env-var RC_API_KEYAdd the export line to your shell profile so the variable is set whenever Codex launches. This writes the server to ~/.codex/config.toml:
config.toml
[mcp_servers.reversecontact]
url = "https://api.reversecontact.com/mcp"
bearer_token_env_var = "RC_API_KEY"Cursor
Create a .cursor/mcp.json file at the root of your project. Cursor connects over HTTP natively, keyed on url (no type field):
.cursor/mcp.json
{
"mcpServers": {
"reversecontact": {
"url": "https://api.reversecontact.com/mcp",
"headers": {
"Authorization": "Bearer rc_your_api_key"
}
}
}
}Gemini CLI
Gemini CLI supports remote Streamable HTTP MCP servers. Add Reverse Contact to ~/.gemini/settings.json for your user account, or .gemini/settings.json for one project:
settings.json
{
"mcpServers": {
"reversecontact": {
"httpUrl": "https://api.reversecontact.com/mcp",
"headers": {
"Authorization": "Bearer rc_your_api_key"
}
}
}
}Run gemini mcp list to check the connection. The Gemini app's custom connector surface is separate and does not support this setup yet.
Other clients (mcp-remote)
Most clients that support HTTP MCP servers accept the same URL and Authorization: Bearer rc_your_api_key header through their own config format. If your MCP client only supports stdio transport, use mcp-remote as a bridge:
mcp-remote
npx mcp-remote https://api.reversecontact.com/mcp \
--header "Authorization: Bearer rc_your_api_key"This works with any client that supports stdio-based MCP servers.
Available tools
Enrichment
| Tool | What it does | Credits | Response |
|---|---|---|---|
enrich_person | Get a person's Social profile from cache, or find it by email/name | 1 (cached) / 2 (by email/name, if found) | Instant |
enrich_person_live | Force a fresh social profile scrape for a person profile from a URL or prs_… id | 2 (live) | Async |
enrich_company | Get a company's Social profile from cache, or find it by domain (description, size, HQ, industry) | 1 (cached) / 2 (by domain, if found) | Instant |
enrich_company_live | Force a fresh social profile scrape for a company profile from a URL or com_… id | 2 (live) | Async |
Search
| Tool | What it does | Credits | Response |
|---|---|---|---|
search_persons | Search people by name, title, company, industry, location, skills, languages, keywords or recent job change | 1 / profile delivered | Instant |
search_persons_lookalike | Find people who look like one seed profile, from its Social profile URL | 1 / profile delivered | Instant |
count_persons | Count the people matching the search_persons filters, without returning any profile | 0 | Instant |
search_companies | Search companies by name, domain, industry, specialities, size, founding year, followers or location, and get full company profiles | 1 / company delivered | Instant |
count_companies | Count the companies matching the search_companies filters, without returning any profile | 0 | Instant |
list_person_search_filters | List the filters accepted by search_persons and count_persons, with their allowed values | 0 | Instant |
list_company_search_filters | List the filters accepted by search_companies and count_companies, with their allowed values | 0 | Instant |
count_persons accepts exactly the filters of search_persons, without cursor or perPage, and returns the total across all pages: the same number as People search count.
search_companies runs Company search: it returns full company profiles, the same shape as the Company profile endpoint, with cursor pagination (perPage from 1 to 100, default 25, and cursor set to the previous nextCursor), and an empty page costs 0 credits. count_companies accepts exactly its filters, without cursor or perPage, and returns the same total as Company search count.
search_persons_lookalike reads its criteria from the seed profile: its current function and sub-function with their tenure, its seniority and its location. It takes only url, perPage (1 to 100, default 25) and cursor, never returns the seed, and returns full profiles shaped like search_persons, with the same cursor pagination. A search filter is refused with LOOKALIKE_FILTERS_NOT_SUPPORTED, and a page with no profile or a seed that is not in the search index yet costs 0 credits. It serves the same results as People lookalike.
The filter catalogs return every filter with its type, description and example. An allowed-value list longer than 50 entries (industries, sub-functions, country codes) is returned as its size in allowedValuesCount; name the field in the fields parameter to get its complete list. They serve the same catalogs as People search available fields and Company search available fields.
Contact
| Tool | What it does | Credits | Response |
|---|---|---|---|
find_email | Find a person's email addresses from a Social profile URL, or from a name and company domain: professional by default, personal or either with emailType | 3 for a professional email, 5 for a personal one, whatever the emailType: any costs 3, 5 or 8 (refunded if no email found) | Async |
find_phone | Find a person's phone numbers from a Social profile URL, or from a name and company domain | 20 (refunded if no phone number found) | Async |
Both tools take a Social profile url, or a name (fullName, or firstName and lastName) with companyDomain. The credits are debited when the task is created and refunded when nothing is found. find_email debits 3 credits, or 5 when emailType is personal or any, and adjusts an any lookup to what it found: 3 for a professional email only, 5 for a personal one only, 8 for both (see Credits by email type). Both tools return a taskId (with webhookId and pollUrl), and the result is retrieved with check_task, as described in Async workflow. A workspace without phone finding access gets CONTACT_PHONE_FINDER_DISABLED from find_phone and is not charged. They run the same lookups as Find Email and Find Phone.
Lists
| Tool | What it does | Credits | Response |
|---|---|---|---|
create_list | Create an empty List of people or of companies, kept in the workspace and shown in the app | 0 | Instant |
list_lists | List the Lists of the workspace, most recently updated first | 0 | Instant |
get_list | Read one List and a page of its members and Pending Intake, or find members by your externalId | 0 | Instant |
add_list_members | Add up to 1,000 people or companies now and get one result per Signal | 1 or 2 per new member | Instant |
import_to_list | Import up to 25,000 Signals, or a public CSV file or Google Sheet, and buy profiles, companies, emails or phone numbers for the members | Per new member and per family bought, within maxCredits | Async |
get_list_operation | Follow an import, with wait up to 20 seconds, and read its per-line results | 0 | Instant |
cancel_list_operation | Stop an import: lines that had not started are never charged | 0 | Instant |
remove_list_members | Remove members from a List, or dismiss Pending Intake lines | 0 | Instant |
export_list | Prepare a CSV of the List, or with format: "ndjson" one JSON object per line, and return a download link valid for 15 minutes | 0 | Instant |
delete_list | Delete a List with its members, once the user asked for it | 0 | Instant |
The List tools run the List endpoints with the same credits. With families and a worst case above 25 credits, import_to_list needs maxCredits, the amount the user agreed to spend: the import stops at that ceiling, and import_to_list called again with the same operationId resumes it without charging anything twice. export_list and get_task_results return a link for the user, not the rows, and a workspace exports one List at a time. delete_list takes confirm: true to state that the user asked for the deletion.
Bulk
| Tool | What it does | Credits | Response |
|---|---|---|---|
bulk_enrich_persons | Enrich up to 25,000 people in one task with their profile, an email or a phone number, without a List | Each item as its unit call, only for what is found, within maxCredits | Async |
get_task_results | Return a download link for the results file, CSV or NDJSON with format, valid for 15 minutes, once the task is completed or cancelled | 0 | Instant |
get_task_rows | Read a page of results into the conversation, even while the task runs: 10 rows by default, 20 at most, as a summary unless detail is full | 0 | Instant |
cancel_task | Stop a task an API key or an AI assistant started: items that had not started are never charged | 0 | Instant |
list_tasks | List every task of the workspace, newest first, whoever started it: Bulk, List imports and Search exports | 0 | Instant |
bulk_enrich_persons runs Bulk: the credits are reserved when the task starts and what an item does not find is given back. Above 25 credits reserved, it needs maxCredits, the amount the user agreed to spend: a task that would reserve more is refused with TASK_MAX_CREDITS, which gives the credits the task needs, and nothing is reserved. Pass idempotencyKey to retry the call safely. Follow the task with check_task and its taskId, with wait up to 20 seconds: kind is bulk, and the answer gives the status, the progress and the credits reserved and spent.
get_task_rows runs Read task results by page: a page stops at the first item not finished, and nextCursor, passed back as cursor, reads on. A summary row gives who was found, their title, company and location; detail: full returns the whole profile, which is heavy, so keep it for the few rows that need it. For the whole file, get_task_results returns a link for the user: a large result never goes through the conversation.
Goals
A goal keeps a long task on your Lists going from one conversation to the next: the request it serves, criteria the server checks on the Lists, the Lists it works on and a credit budget. A new conversation, or another AI assistant, finds the goal with list_goals and resumes it with get_goal.
| Tool | What it does | Credits | Response |
|---|---|---|---|
create_goal | Open a goal: the request it serves, the criteria to meet on your Lists, the Lists it works on and its credit budget | 0 | Instant |
list_goals | List the goals of the workspace, newest first: the open ones (active, paused or blocked) by default, every goal, or one status | 0 | Instant |
get_goal | Read where a goal stands, to resume it: each criterion measured now on the Lists, the budget spent, held and left, the operations still running, the plan and the decisions taken | 0 | Instant |
update_goal | Steer a goal: revise it, pause, block or cancel it, complete it, record a decision, update the plan, or take over from an assistant that stopped | 0 | Instant |
The criteria count members of your Lists: the members of a List, the members with a profile, company details, an email or a phone number, or the members with a value in one of your columns. update_goal with complete closes the goal only when every criterion holds, and accept_partial closes it with a reason when the result is enough. A goal described in words (described criteria) has nothing to measure and closes with accept_partial.
The assistant that opens a goal is its Pilot. A goal has one Pilot at a time, and the Pilot's lease runs for 15 minutes after its last action: once it lapses, another assistant takes over with update_goal (take_over), and the goal keeps its budget.
Pass the goalId to a billed tool (enrich_person, enrich_person_live, enrich_company, enrich_company_live, search_persons, search_persons_lookalike, search_companies, find_email, find_phone, add_list_members or import_to_list) and the call spends within the goal's budget: it runs without asking the user again, import_to_list included above 25 credits, and a call that would go past the budget left is refused with GOAL_BUDGET_REFUSED and its cost, with nothing charged. Only the Pilot spends on a goal, and only while the goal is active. Set budget.maxCredits to the amount the user agreed to spend: a goal without a budget puts no ceiling on the calls that carry its goalId, and raising the budget takes update_goal with revise.
Goals are free and need the Lists scope on the API key. A workspace keeps up to 20 open goals, and one at a time during the free trial. An open goal with no Pilot and nothing running for 30 days is paused.
Utility (free)
| Tool | What it does | Credits | Response |
|---|---|---|---|
check_person | Check whether a person profile is cached and how fresh it is, from a Social URL or prs_… id | 0 | Instant |
check_company | Check whether a company profile is cached and how fresh it is, from a Social URL or com_… id | 0 | Instant |
check_usage | Check your credit balance and rate limit status | 0 | Instant |
check_task | Follow a task, with wait up to 20 seconds: a live enrichment or a contact lookup (kind: lookup), or a Bulk task (kind: bulk) | 0 | Instant |
enrich_company takes a Social url or a domain. A domain runs Enrich company and returns the full company profile under data.company, and a domain that matches no company costs 0 credits. When you send both, the url is used.
Example prompts
Once the MCP server is connected, ask your AI agent in natural language. These examples map to the tools above and use the same credits as the REST API.
- Enrich a person from an email:
Enrich the Social profile for
alex@acme.comand summarize current title, company, and recent experience. - Find a company from a domain:
Enrich the company with domain
stripe.comand return its industry, employee range, headquarters, and a one-paragraph description. - Search people with filters:
Find people who are Heads of Sales or VPs of Sales at SaaS companies in the United States. Return the first page of results with name, title, and company.
- Size an audience before paying for it:
How many sales directors work in France? Count them first, and return the first 25 profiles only if there are fewer than 5,000.
- Search companies with filters:
How many fintech companies with 51 to 200 employees, founded since 2015, are headquartered in France? Count them first, then list the first 25 with name, domain, and size.
- Check usage before a batch:
Check my Reverse Contact credit balance and rate limit status before I run a larger enrichment batch.
- Run an async live enrichment:
Live-enrich the Social profile
https://www.social.com/in/examplewithenrich_person_liveand, if the tool returns a task id, poll until the result is ready, then summarize the profile. - Find people like a profile:
Find 25 people who look like
https://www.social.com/in/exampleand list their name, title, company and location. - Find a professional email:
Find the professional email address of Jane Doe at
acme.com, wait for the result, then give me the address. - Keep people in a List and buy their emails:
Create a List called "Fintech founders", add the people of my last search to it, then find their professional emails. Tell me the worst case cost first and ask me before you spend it.
- Enrich a file in bulk:
Enrich these 300 Social profile URLs with their profile and professional email in one bulk task, wait for it to finish, then give me the link to the results CSV.
- Work toward a goal across conversations:
Open a goal: my List "Fintech founders" should hold 200 people with a professional email, within a budget of 1,000 credits. Start now, and when I come back in a new conversation, resume the goal and tell me where it stands.
For live enrichments and contact lookups, the agent receives a taskId from enrich_person_live, enrich_company_live, find_email or find_phone and should call check_task until the status is succeeded or errored. You usually do not need to manage that loop yourself.
Async workflow
The live tools (enrich_person_live, enrich_company_live) and the contact tools (find_email, find_phone) run asynchronously. They return a taskId instead of data:
Async response
{
"status": "created",
"webhookId": "abc123",
"pollUrl": "/v2/webhooks/abc123",
"taskId": "abc123",
"message": "Scraping LinkedIn profile. Get the result with check_task (wait: 20)."
}Use check_task with the taskId to poll for results, with wait: 20 so each call waits for the task to finish. Tasks typically complete in 10 to 60 seconds. While a task runs, check_task answers with the status in_progress, and the task ends succeeded or errored.
When the task has succeeded, check_task returns the data payload. Your AI agent handles this polling automatically.
Credits and rate limits
MCP tools consume the same credits and respect the same rate limits as the REST API:
- MCP calls use the same endpoint pricing as REST.
- MCP calls count toward the same gateway RPM limits as REST API calls.
count_personsandcount_companiesare free but still count, like their REST endpoints;check_usage,check_taskand the two filter catalogs do not.
Use check_usage to inspect your current balance before expensive operations, and count_persons or count_companies to size a search for free before search_persons or search_companies bills each profile or company delivered.
Rate limits covers quotas and throttling.
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
Authentication required (code -32001) | Missing or invalid credentials | OAuth clients: re-authenticate from the client (the access expires if its key is deleted). API key clients: check the key is active and the Bearer prefix is present |
SSE streaming not supported (code -32601) | Client sent a GET request | Your client must use POST. Use mcp-remote if it defaults to SSE |
RATE_LIMIT_EXCEEDED | Too many requests per minute | Wait for the rate limit window to reset. Check limits with check_usage |
INSUFFICIENT_CREDITS | Not enough credits for the operation | Top up credits from the dashboard |
KEY_CREDIT_LIMIT_REACHED | The API key the client uses reached one of its credit limits (0 credits) | Wait for the daily or monthly reset, or raise or reset the limit in API Keys |
LOOKALIKE_FILTERS_NOT_SUPPORTED | search_persons_lookalike received a search filter (0 credits) | Send only url, perPage and cursor, or use search_persons to combine filters |
CONTACT_PHONE_FINDER_DISABLED | Phone finding is not enabled for the workspace (0 credits) | Use find_email, or ask us to enable phone finding |
TASK_MAX_CREDITS | bulk_enrich_persons would reserve more than 25 credits without maxCredits, or more than maxCredits (0 credits) | Ask the user to agree to the credits the error gives, then call again with that maxCredits, or send fewer items |
GOAL_BUDGET_REFUSED | A call with a goalId does not fit the goal: the budget left is too small, the goal is not active, the tool is outside the goal, or the workspace lacks credits (0 credits) | Read the goal with get_goal, then ask the user to raise the budget (update_goal with revise) or to resume the goal |
GOAL_PILOT_CONFLICT | Another assistant is the Pilot of the goal (0 credits) | Wait until its lease lapses, 15 minutes after its last action, then call update_goal with take_over |
GOAL_LIMIT_REACHED | The workspace already has 20 open goals, or 1 during the free trial (0 credits) | Complete or cancel a goal with update_goal, then open the new one |
| Connection timeout | Client cannot reach the server | Verify the URL is https://api.reversecontact.com/mcp and your network allows HTTPS |
FAQ
Do I need an API key to use the Reverse Contact MCP server?
No, not with a client that supports OAuth (claude.ai, Cowork, Claude Desktop, Claude Code, mobile and ChatGPT): you sign in with your account, approve the access in your browser, and a dedicated API key named MCP - {app} is created in your workspace automatically. Every other MCP client authenticates with an active Reverse Contact API key (rc_*) in the Authorization header.
Do Reverse Contact MCP tools cost the same as REST API calls?
Yes, Reverse Contact MCP tools use the same endpoint pricing and count toward the same gateway RPM limits as the REST API. count_persons and count_companies are free but still count toward RPM, while check_usage, check_task, list_person_search_filters and list_company_search_filters do not. Details on quotas and throttling are in Rate limits.
How long does a live enrichment or email lookup take over MCP?
The asynchronous Reverse Contact MCP tools (enrich_person_live, enrich_company_live, find_email and find_phone) return a taskId instead of data, and tasks typically complete in 10 to 60 seconds. The AI agent calls check_task with that taskId until the status is succeeded or errored, so you usually do not need to manage that loop yourself. The full flow is in Async workflow.
Am I charged when the MCP email or phone finder finds nothing?
No. The Reverse Contact MCP tools find_email and find_phone debit credits when the task is created and refund them when no email or phone number is found. find_email is billed on the emails found, not on emailType: 3 credits for a professional email and 5 for a personal one, so a lookup with emailType set to any costs 3, 5 or 8 (8 only when it finds both), and find_phone costs 20 credits.
Can the Reverse Contact MCP server look up a company by its domain?
Yes. The Reverse Contact MCP tool enrich_company takes a domain and returns the full company profile. It costs 2 credits when a company is found and 0 when none is. With a Social url instead, enrich_company costs 1 credit, and the url is used when both are sent.
Last verified