Skip to main content
The SphereScout MCP server has 12 tools. Ten only read data. Two start exports, which spend credits.

​
Classification

  • Read tools return data and change nothing in the account. Their MCP annotations are readOnlyHint: true, destructiveHint: false, idempotentHint: true.
  • Sensitive write tools spend credits, which can’t be undone, and save a file to the account. They need the user’s approval every time. Their annotations are readOnlyHint: false, destructiveHint: true, idempotentHint: false.
  • Every tool works only on SphereScout’s own database and the signed-in account: openWorldHint: false.
The export tools only charge what the user approved. Pass the count the user saw (export_quote_id or expected_credits): if the search grew, the export is refused or fails without charging, and the answer gives the new cost to approve.

​
find_category

Finds the category for a kind of business. Categories are named in English. Returns categories, each with category_id, name, match_rank (0 is an exact match), matched_field, matched_value and substring_only (true when the term only appears inside another word). Errors invalid_argument.

​
list_countries

Lists the countries SphereScout covers. No inputs. Returns countries, each with country (ISO alpha-2 code) and name.

​
find_location

Finds a city, county or region by name. Places are stored under their local-language names (München, Lisboa). Returns locations, each with location_ref (level and id, used in filters.locations), name, kind (state/region, county/department or city/commune), its state and county, and exact_name. The answer can add:
  • needs_clarification, clarify_on and clarification_hint when the name is ambiguous;
  • namesakes when several places share the name and level;
  • city_zones when a city is stored as several zones, with all of them;
  • big_city when a big city’s neighborhoods are stored under their own names, with those places.
Errors invalid_argument, invalid_country, country_not_covered.

​
list_locations

Lists every place of one level: all states, all counties in a state, or all cities in a county. Returns kind, count and locations, each with location_ref and name. Errors invalid_argument, invalid_country, country_not_covered.

​
preview_businesses

Counts businesses by category and place, and gives what an export of them would cost. filters takes: Returns
  • count and credit_cost (the same number: one credit per business);
  • search, the search in words, and country_data_updated;
  • contact_coverage: how many have an email, a phone, both, either or neither (up to 20,000 matches, or on request);
  • sample or the requested page;
  • for accounts that can export, an export block with an export_quote_id valid for 15 minutes, a confirm_with sentence for the user’s approval, and cheaper alternatives (only businesses with an email, a phone, or either), each with its own quote;
  • for accounts that can’t, export.available: false and a plans_url.
Side effects None. The quote is kept for 15 minutes so start_export can use it. Errors invalid_argument, invalid_country, country_not_covered, personal_email_filter_requires_plan.

​
get_account

Shows the signed-in account’s plan and credits. No inputs. Returns email, plan, subscription_status, access (full or free), can_export, can_filter_personal_emails, export_credits_available, and plans_url for free accounts.

​
Export

​
start_export

Sensitive write: spends credits. Ask the user to approve the confirm_with sentence from preview_businesses before every call.
Exports businesses with their contacts to a file in the signed-in account. Side effects
  • Spends 1 credit per exported business, never more than the approved count.
  • Saves the file to the account’s export history.
  • 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.
  • Calling again with the same arguments within 15 minutes returns the same export with already_started: true and no new charge.
Returns search_id, status, credits_charged and destination (the account and its export history). A small export comes back completed with the fields of get_export; otherwise poll get_export after poll_after_seconds. Errors invalid_argument, quote_invalid, quote_expired, credit_cost_changed, insufficient_credits, no_leads_found, export_in_progress, personal_email_filter_requires_plan, api_subscription_required, insufficient_scope.

​
get_export

Returns an export’s status and, once it’s ready, its file. Returns search_id, status and row_count. Then, depending on the status:
  • pending or processing: poll_after_seconds;
  • completed: credits_charged, download_url (no sign-in needed), download_expires_at (7 days after the file was made), file_size_mb, filename, search and columns;
  • failed: failure, user_message and credits_refunded. An update export that grew beyond its approved credits fails with credit_limit_exceeded and gives required_credits; one with nothing new fails with no_fresh_data. Neither is charged.
Errors search_not_found, download_expired.

​
read_export_rows

Returns the rows of a finished export, with their contacts. The export is already paid for, so reading it is free. Returns total_rows, page, pages, columns and rows. Empty cells are left out of each row. Errors invalid_argument, search_not_found, download_expired.

​
Export history

​
list_exports

Lists the account’s past exports, newest first. Returns exports, each with search_id, title (category · place), created_at, status, rows, credits_charged, format, file_available, download_expires_at, and the updates made from it.

​
check_export_updates

Counts what changed in a past export’s list since it was last exported, and what exporting only those businesses would cost. Returns has_updates, credit_cost, changes (new businesses, businesses with their first email, new emails, new phones), since and checked_at. With a plan that includes update exports, an update_export block gives expected_credits and a confirm_with sentence; otherwise update_export.available: false and a plans_url. Side effects None. A list is checked at most once a day; a later call returns the latest check and next_check_at. Errors search_not_found.

​
start_update_export

Sensitive write: spends credits. Ask the user to approve the confirm_with sentence from check_export_updates before every call.
Exports only the businesses that changed since a past export, to a file in the signed-in account. Side effects
  • Spends 1 credit per exported business, at most expected_credits. If the update grew beyond it, nothing is charged and get_export gives the new cost.
  • Saves the file to the account’s export history.
  • 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.
  • Calling again with the same arguments within 15 minutes returns the same export.
Returns search_id, status, credit_limit and destination. Poll get_export for the file. Errors invalid_argument, search_not_found, insufficient_credits, fresh_export_subscription_required, api_subscription_required, insufficient_scope.