Connect AI agents (MCP)

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, and more, all through natural conversation.

ReverseContact exposes 16 tools via MCP. Same data, same credits, same rate limits as the REST API.

Prerequisites

• A ReverseContact 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 the Authorization header. Create one from API Keys.

Server details

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

ReverseContact is published in the Claude connector directory, so there is nothing to paste and no API key involved:

1. Open our page in the Claude connector directory.
2. Click Connect: your browser opens the ReverseContact 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.

Prefer to add it by hand, or 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. The fastest path is one command in your terminal, no API key needed:

claude mcp add --transport http reversecontact https://api.reversecontact.com/mcp

Then 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:

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:

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

ChatGPT

ReverseContact is published in the ChatGPT plugin directory, so there is nothing to paste and no API key involved:

1. Open our page in the ChatGPT plugin directory.
2. Click Add: your browser opens the ReverseContact 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.

Prefer to add it by hand, or your organization restricts the directory? Enable Developer mode under Settings > Connectors > Advanced settings (paid ChatGPT plan: Plus, Pro, Business, Enterprise or Edu), then Create a connector: name it ReverseContact, 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:

export RC_API_KEY="rc_your_api_key"
codex mcp add reversecontact \
  --url https://api.reversecontact.com/mcp \
  --bearer-token-env-var RC_API_KEY

Add the export line to your shell profile so the variable is set whenever Codex launches. This writes the server to ~/.codex/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):

{
  "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 ReverseContact to ~/.gemini/settings.json for your user account, or .gemini/settings.json for one project:

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

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

Search

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_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

Both tools take a LinkedIn profile url, or a name (fullName, or firstName and lastName) with companyDomain. The credits are debited when the job is created and refunded when nothing is found. They 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.

Utility (free)

Company lookup by domain is not available as an MCP tool. To go from a domain to a company profile, search with search_companies and its companyDomain filter, then pass the LinkedIn URL it returns to enrich_company.

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.

1. Enrich a person from an email

   Enrich the LinkedIn profile for alex@acme.com and summarize current title, company, and recent experience.

2. Find and enrich a company from a domain

   Search for the company with domain stripe.com, then enrich its LinkedIn profile and return industry, employee range, headquarters, and a one-paragraph description.

3. 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.

4. 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.

5. Search companies with filters

   Search for fintech companies with 50 to 200 employees headquartered in France. List name, domain, and size.

6. Check usage before a batch

   Check my ReverseContact credit balance and rate limit status before I run a larger enrichment batch.

7. Async live enrichment workflow

   Live-enrich the LinkedIn profile https://www.linkedin.com/in/example with enrich_person_live and, if the tool returns a task id, poll until the result is ready, then summarize the profile.

8. Find people like a profile

   Find 25 people who look like https://www.linkedin.com/in/example and list their name, title, company and location.

9. Find a professional email

   Find the professional email address of Jane Doe at acme.com, wait for the result, then give me the address.

Tip: 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 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:

{
  "taskId": "abc123",
  "status": "processing",
  "message": "Scraping LinkedIn profile. Poll with check_task in ~10 seconds."
}

Use check_task with the taskId to poll for results. Tasks typically complete in 10–60 seconds.

Status flow: in_progress → succeeded or errored

When succeeded, check_task returns the full data payload. Your AI agent handles this polling automatically. Just ask for what you need.

Credits and rate limits

MCP tools consume the same credits and respect the same rate limits as the REST API. That means:

• MCP calls use the same endpoint pricing as REST.
• MCP calls count toward the same gateway RPM limits as REST API calls. count_persons is free but still counts, like its REST endpoint; check_usage, check_task and the two filter catalogs do not.
• Agent LLM turns are different: they consume credits but do not affect gateway RPM until the Agent triggers a real tool call.

Use check_usage to inspect your current balance before expensive operations, and count_persons to size a people search for free before search_persons bills each profile delivered.

See Rate limits & credits for details on quotas and throttling.

Troubleshooting