MCP server

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.

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
ChatGPT
Claude Code
Codex
Cursor

Add a custom connector with the server URL, then sign in to SphereScout when Claude asks. See Claude’s guide to custom connectors.

claude mcp add --transport http spherescout https://mcp.spherescout.io/mcp

codex mcp add spherescout --url https://mcp.spherescout.io/mcp
codex mcp login spherescout

{ "mcpServers": { "spherescout": { "url": "https://mcp.spherescout.io/mcp" } } }

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
`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 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 and Plans.

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:

{
  "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 describes what SphereScout collects when you use an AI assistant.

Tool reference

Every tool’s inputs, outputs, classification, side effects and errors.

API keys

Create a key for clients that don’t support OAuth.

Get Started

Core Concepts

Using SphereScout

Plans & Billing

API Access

Help

MCP server

Server URL

Connect

Plans and credits

Export statuses

Errors

Limits

Data handling

Tool reference

API keys

​Server URL

​Connect

​Sign-in and permissions

​Plans and credits

​Export statuses

​Errors

​Limits

​Data handling

Tool reference

API keys

Server URL

Connect

Sign-in and permissions

Plans and credits

Export statuses

Errors

Limits

Data handling