# MCP server

The GetProspect MCP server lets an AI assistant search people and companies, enrich contacts and verify emails in your
workspace, using the same data and credits as the API.

- Server URL: `https://api.getprospect.com/mcp`
- Transport: Streamable HTTP
- Authentication: sign in with GetProspect (OAuth), or an API key in the `x-api-key` header

The tools call the same v2 endpoints as the REST API, so [rate limits](#usage-and-limits) and
[credits](https://getprospect.com/api-docs/credits-and-limits.md) follow the same policy.

## Authentication

**Sign in with GetProspect** is the default. The client discovers the server's OAuth metadata and registers itself
(OAuth 2.1 with PKCE and dynamic client registration), then opens a GetProspect page where you sign in and pick the
workspace it may use. You paste nothing. The assistant acts as you, in that workspace, and spends that workspace's
credits.

Access tokens last 15 minutes and refresh on their own. A connection that is used at least every 60 days stays
signed in.

**API key** is for clients that only take headers. Create a key on the
[API page](https://app.getprospect.com/api) and send it as `x-api-key`, as for the REST API (see
[Authentication](https://getprospect.com/api-docs/authentication.md)). The key acts in the workspace where you created it.

Credentials go in headers only. The server refuses an API key in the query string, and an API key must be sent as
`x-api-key`, not as `Authorization: Bearer` (that header carries OAuth tokens).

A missing, expired or revoked credential returns HTTP `401`, which makes a signing-in client start the sign-in again.

## Add it to your assistant

The same steps are on the [Integrations](https://app.getprospect.com/integrations) page of the app, with copy buttons.
Menu names change as clients update; the URL is always the one above.

### Claude (web and Desktop)

1. Open **Settings**, then **Connectors**, then **Add custom connector**.
2. Paste `https://api.getprospect.com/mcp`.
3. Click **Connect** and sign in with GetProspect.

### Claude Code

```bash
claude mcp add --transport http getprospect https://api.getprospect.com/mcp
```

Then type `/mcp` in Claude Code and sign in.

### ChatGPT

1. Open **Settings**, then **Apps & Connectors**, then **Advanced**, and turn on **Developer mode**.
2. Create a connector, paste the server URL and choose OAuth.

Developer mode needs a paid ChatGPT plan.

### Cursor

Use the **Add to Cursor** button on the [Integrations](https://app.getprospect.com/integrations) page, then sign in when
Cursor asks. Or add it to `mcp.json` with an API key:

```json
{
  "mcpServers": {
    "getprospect": {
      "url": "https://api.getprospect.com/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}
```

### VS Code

Use the **Add to VS Code** button on the [Integrations](https://app.getprospect.com/integrations) page, then sign in
when VS Code asks. Or add it to `mcp.json` with an API key:

```json
{
  "servers": {
    "getprospect": {
      "type": "http",
      "url": "https://api.getprospect.com/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}
```

### Grok

Open grok.com/connectors, choose **New connector**, then **Custom**, paste the server URL and sign in. A paid Grok plan
may be required.

### Perplexity

Open **Settings**, then **Connectors**, then **Add connector**, then **Custom (remote)**. Paste the server URL and
choose OAuth and Streamable HTTP. A paid Perplexity plan may be required.

### Other clients

Any MCP client that takes a server URL can sign in the same way. If yours only takes headers, use the `mcpServers`
shape shown for Cursor.

## Tools

The server offers 16 tools. Free tools never spend credits.

| Tool | What it does | Cost |
| --- | --- | --- |
| `get_account` | The signed-in user, workspace, plan, credit balances and rate limits | Free |
| `lookup_filter_values` | The exact values the search filters accept: locations, job titles, industries, technologies, keywords, companies, people and the closed lists (seniorities, departments, employee ranges, countries) | Free |
| `search_people` | Search people with filters; shows whether each person has an email, without revealing it | Free |
| `search_companies` | Search companies with filters | Free |
| `enrich_companies` | Look up 1 to 50 companies by id, LinkedIn, domain or name | Free |
| `list_lists` | Your people and company lists, with record counts | Free |
| `create_list` | Create an empty people or company list | Free |
| `save_companies` | Save up to 500 companies, optionally into lists | Free |
| `list_bulk_enrichments` | Your bulk enrichment jobs, newest first | Free |
| `get_bulk_enrichment` | One bulk job: status, progress, counts, credits used and its results | Free |
| `estimate_cost` | The worst-case credit cost of a paid call, before you make it | Free |
| `enrich_people` | Look up 1 to 50 people and reveal their business email, and optionally their mobile phone | 1 email credit per newly revealed email, 1 phone credit per phone found |
| `find_email` | Find a business email from a name and a company. A long search answers "still searching": call again after the seconds it gives | 1 email credit if a new valid email is found; nothing until found |
| `verify_email` | Check whether an email is deliverable | 1 verification credit for a valid or invalid verdict |
| `save_people` | Save up to 500 people (ids from `search_people`, or up to 50 LinkedIn URLs) into 1 to 20 people lists (`list_ids`) and hand over their stored emails | 1 email credit per person whose email you do not own yet |
| `start_bulk_enrichment` | Start a background job for up to 10,000 people or companies | People: per email and phone found. Companies: free |

Not found is free. An email your workspace already owns is free again anywhere. See
[Credits and rate limits](https://getprospect.com/api-docs/credits-and-limits.md) for the full rules.

### Results tables

In clients that support [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) (Claude, ChatGPT and VS Code),
`search_people`, `search_companies`, `enrich_people`, `enrich_companies`, `save_people` and `save_companies` show
their results as an interactive table in the GetProspect style: company logos, email status, **Reveal email**,
row selection and paging. Selecting rows and choosing an action sends a message to your assistant, so a paid
action still shows its credit quote first. Paging a search is free. Other clients get the same results as text.

## How credits work

Searching, filter lookups, lists and company lookups are free. Only the paid tools in the table spend credits.

**Quote before spend.** Before a paid tool runs, the server works out its worst-case cost. Each person costs at most 1
email credit and 1 phone credit, and every item not known to be owned counts.

- At or under **10 credits** per call (all credit types together), the call runs straight away.
- Above 10 credits, the call spends nothing and returns a quote with the worst case and your balance. The assistant
  should show it to you and ask. Once you agree, it calls the tool again with `max_credits` set to at least the
  quoted amount.
- A call whose worst case is above `max_credits` is refused and spends nothing. Because the quote is an upper bound,
  `max_credits` at or above it caps what this call can charge. A bulk job charges as it runs and stops early if the
  balance runs out.

The 10-credit threshold is the default. `estimate_cost` shows the current quote.

Actual spend is usually lower than the quote: emails you already own and lookups that find nothing are free. Paid
results report `credits_used` and your balance when it can be read. For a bulk job, `get_bulk_enrichment` reports
the credits used.

`estimate_cost` returns the same quote on request, so the assistant can check before it asks you. It takes the paid
tool's name (`action`) and the arguments that tool would get.

> **Quotes are on trust**
>
> The server cannot prove that you saw a quote. The protection is the quote contract in the tool descriptions, the
> approval prompt most clients show for tools that are not read-only, and the `max_credits` cap. Review a tool call
> before you approve it.

For more than 50 people, the assistant should use `start_bulk_enrichment` instead of repeated `enrich_people` calls.
Poll the job with `get_bulk_enrichment`.

## Prompts

The server also offers three ready-made prompts. Clients that support MCP prompts show them in a menu.

| Prompt | Input | What it does |
| --- | --- | --- |
| `find_prospects` | `icp`: the ideal customer profile | Maps it to filters, searches, shows the total and best matches, and offers to enrich |
| `research_account` | `domain`: a company website | Summarizes the company and lists its decision makers, without spending credits |
| `enrich_contacts` | `contacts`: one person per line | Enriches a pasted list, getting the cost first and asking before it spends |

## Usage and limits

- MCP requests are their own source. They show as **MCP** on the [Usage](https://app.getprospect.com/usage) page, in
  the source filter and the breakdown.
- MCP calls follow the same rate-limit policy as the REST API (see
  [Credits and rate limits](https://getprospect.com/api-docs/credits-and-limits.md)). Moving to MCP does not raise them. A limited call returns
  a tool error with the seconds to wait.
- Results are capped at about 20,000 tokens per call. When a result is cut, the text says what was cut and how to
  narrow the search.

## Disconnect

Open **Settings**, then **Security**, and find the assistant under **Active sessions**, labeled with its name and
"(connected app)". Click **Disconnect**. The assistant can no longer refresh its sign-in; an access token already
issued can keep working for up to 15 minutes. An API key stops working when you delete it on the
[API page](https://app.getprospect.com/api).

A user can have up to 10 connections (sign-ins) per workspace, shared by MCP assistants, Zapier and the Sheets
add-on. Connecting another signs out the oldest. Browser sign-ins are not affected.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `401` or "needs to sign in" | The sign-in expired or was disconnected. Reconnect the server in your client and sign in again. With an API key, check that the key still exists on the [API page](https://app.getprospect.com/api) |
| The tool answers with a quote and does not run | Expected above 10 credits. Check the cost, then ask the assistant to continue. It calls the tool again with `max_credits` set to the quote |
| "max_credits is below the worst case" | The cap is lower than the quote. Nothing was spent. Approve the quoted amount and call again |
| "Needs N email credits, workspace has M" | The workspace is short of credits. Buy more or ask for fewer people. See [Credits and rate limits](https://getprospect.com/api-docs/credits-and-limits.md) |
| "Rate limited, retry after N s" | If you are rate limited, wait the stated seconds and retry |
| A filter value is rejected | Use `lookup_filter_values` and pass the value exactly as returned |
| Wrong workspace | The connection is tied to the workspace you picked when signing in. Disconnect it and sign in again with the right one |