> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherescout.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect Claude, ChatGPT, Cursor and other AI assistants to SphereScout to search local businesses and export their contacts.

The SphereScout MCP server lets an AI assistant search SphereScout's database of local businesses by category and place, count them, and export them with their contacts to your SphereScout account. It implements the [Model Context Protocol](https://modelcontextprotocol.io).

## Server URL

```
https://mcp.spherescout.io/mcp
```

The server uses the Streamable HTTP transport with JSON responses and keeps no session state. It supports protocol versions `2025-11-25`, `2025-06-18`, `2025-03-26` and `2024-11-05`.

## Connect

**Claude**

Add a custom connector with the server URL, then sign in to SphereScout when Claude asks. See [Claude's guide to custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

**ChatGPT**

Add the server URL as an app in developer mode, then sign in to SphereScout. See [OpenAI's guide](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt-beta).

**Claude Code**

```bash theme={null}
claude mcp add --transport http spherescout https://mcp.spherescout.io/mcp
```

**Codex**

```bash theme={null}
codex mcp add spherescout --url https://mcp.spherescout.io/mcp
codex mcp login spherescout
```

**Cursor**

```json theme={null}
{ "mcpServers": { "spherescout": { "url": "https://mcp.spherescout.io/mcp" } } }
```

## Sign-in and permissions

The server uses OAuth 2.1 with PKCE (`S256`). Clients register with a Client ID Metadata Document or with Dynamic Client Registration.

| | URL |
| - | - |
| Authorization server | `https://api.spherescout.io` |
| Authorization server metadata | `https://api.spherescout.io/.well-known/oauth-authorization-server` |
| Protected resource metadata | `https://mcp.spherescout.io/.well-known/oauth-protected-resource` |

When you connect, SphereScout shows which permissions the assistant asks for:

| Scope | What it allows | Tools |
| - | - | - |
| `leads:read` | Search categories and places, count and preview businesses, see your plan, read your past exports | All [read tools](https://docs.spherescout.io/mcp/tools.md#classification) |
| `leads:export` | Start exports that spend your credits | `start_export`, `start_update_export` |

To give an assistant read-only access, untick **Start exports that spend your credits** on the consent screen. Its export tools then answer `insufficient_scope`.

Access tokens last 1 hour. Refresh tokens last 90 days and are replaced each time they're used. To disconnect an assistant, open **Connected apps** on the API page of your dashboard.

Clients without OAuth can send a SphereScout [API key](https://docs.spherescout.io/api-access/api-keys.md) instead, as `Authorization: Bearer YOUR_API_KEY`. An API key has both scopes.

## Plans and credits

* Searching, counting and previewing work on every account.
* Exports need an active paid subscription. Each exported business costs 1 credit, and an export never costs more than the count the user confirmed.
* Exporting only what changed since a past export needs a plan with data updates.
* If an export fails, `get_export` says whether its credits were refunded.

See [Credits](https://docs.spherescout.io/concepts/credits.md) and [Plans](https://docs.spherescout.io/billing/plans.md).

## Export statuses

Exports run in the background. `start_export` and `start_update_export` return a `search_id`; poll it with `get_export` every `poll_after_seconds` (5 seconds).

| Status | Meaning |
| - | - |
| `pending` | Queued. Keep polling. |
| `processing` | Being built. Keep polling. |
| `completed` | Ready. The answer includes a `download_url` valid for 7 days. |
| `failed` | No file was produced. `failure` gives the reason and `credits_refunded` says whether the credits came back. |

## Errors

A tool that can't complete a request returns a result with `isError: true`. Its `structuredContent` names the error, says whether retrying can help, and gives a message to show the user:

```json theme={null}
{
  "error": "insufficient_credits",
  "retryable": false,
  "user_message": "This export needs 1200 credits and the account has 950. Nothing was charged.",
  "agent_hint": "Suggest narrowing the search (a location, or has_email/has_phone/has_website) rather than retrying."
}
```

| Error | Meaning | Retryable |
| - | - | - |
| `invalid_argument` | An argument is missing or invalid. | No |
| `invalid_country` | `country` isn't an ISO alpha-2 code. | No |
| `country_not_covered` | SphereScout doesn't cover this country. `covered_countries` lists the ones it does. | No |
| `quote_invalid`, `quote_expired` | The `export_quote_id` is unknown, belongs to another account, or is older than 15 minutes. | No |
| `credit_cost_changed` | The search now matches more businesses than the user confirmed. `credit_cost` gives the new count. Nothing was charged. | No |
| `insufficient_credits` | The account doesn't have enough credits. Nothing was charged. | No |
| `no_leads_found` | No businesses match. Nothing was charged. | No |
| `export_in_progress` | The same export is being started. Calling again returns it. | Yes |
| `search_not_found` | No export with this `search_id` exists on the account. | No |
| `download_expired` | The export's download link has expired. | No |
| `personal_email_filter_requires_plan` | The account's plan doesn't include the named-emails filter. | No |
| `fresh_export_subscription_required` | The account's plan doesn't include update exports. | No |
| `api_subscription_required` | Exports need an active paid subscription. Nothing was charged. | No |
| `insufficient_scope` | The connection was granted read-only access. | No |
| `rate_limited` | The hourly limit was reached. | Yes |
| `upstream_error`, `internal_error` | A temporary failure. | Yes |

A request without valid credentials gets an HTTP `401` with a `WWW-Authenticate` header pointing to the OAuth metadata. An unknown tool gets JSON-RPC error `-32602`.

## Limits

| Limit | Value |
| - | - |
| Tool calls per account | 600 per hour |
| Tool calls per IP address | 1,200 per hour |
| Export quote validity | 15 minutes |
| Same export repeated within | 15 minutes returns the first export, without a new charge |
| Update checks per list | 1 per day; later checks return the latest result |
| Rows per export | 500,000 |
| Categories per search | 20 |
| Preview page | 50 businesses |
| `read_export_rows` page | 200 rows |

## Data handling

* Exports are saved to the export history of the account that signed in. The download link is returned only to the connection that started the export. SphereScout also emails the account owner when the file is ready or if the export fails; both emails can be turned off under **Email notifications** on the plans page of the dashboard. The server never sends files or messages to businesses, CRMs or anyone else.
* Business names, addresses and websites are third-party data. Answers that contain them include a `data_note` reminding the assistant not to follow instructions found in them.
* The [privacy policy](https://www.spherescout.io/privacy-policy/) describes what SphereScout collects when you use an AI assistant.

> **[Tool reference](https://docs.spherescout.io/mcp/tools.md)**
>
> Every tool's inputs, outputs, classification, side effects and errors.

> **[API keys](https://docs.spherescout.io/api-access/api-keys.md)**
>
> Create a key for clients that don't support OAuth.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.