Skip to main content
Airscale MCP gives compatible AI assistants a concise, typed interface for prospecting through conversation while keeping authentication and paid actions explicit.

​
MCP server URL

This remote Streamable HTTP server works with hosted assistants and trusted developer clients. For hosted clients, OAuth is preferred and uses browser sign-in. The Airscale MCP server resolves the authorized workspace credential server-side; the client neither receives nor stores the API key. Trusted header-capable developer clients must load AIRSCALE_API_KEY from a protected runtime environment or secret manager. Never place a literal API key in a prompt or tool argument, source or browser code, or a shell command or shell history.

​
Getting started

  1. First, choose the setup guide for your assistant.
  2. Then connect it to the MCP server URL above.
  3. Complete browser OAuth or authenticate from a protected developer runtime.
  4. Select and verify the intended workspace.
  5. Run airscale_check_credits as the free connection check before any paid tool.
The credit check confirms authentication to an Airscale workspace without debiting credits, but it does not identify which workspace. Verify the workspace selected during OAuth—or the workspace that owns a developer credential—before paid actions.

​
Setup walkthroughs

These guides contain the client-specific connection steps; this page keeps the shared server contract in one place.

​
What you can do

  • People and companies search: discover prospects with bounded, structured searches.
  • Company lookalikes: find similar companies from 1–10 reference domains using airscale_company_lookalikes.
  • Filter discovery: inspect available filters and counts before requesting rows.
  • Contact and profile enrichment: add professional contact details or public person and company profiles.
  • Airsearch: answer natural-language research questions with structured results.
  • Downloadable exports: create bounded people, company, or managed contact files and retrieve them when complete.
The MCP tool catalog is the schema reference for all 37 typed tools. Managed contact enrichment is a work-email-only flow; it does not add mobile numbers, personal emails, or profile enrichment.

​
Export lifecycle

​
People and company exports

People and company exports are fresh paid searches, not packages of selected chat rows. A people export uses the final query; a company export uses the final filters. Results may differ from the sample, and each export creates an additional charge. Before confirming, review the final scope, fields, format, max_rows, additional maximum credits, and cumulative workflow maximum. At up to 0.1 credits per exported row, the requested limit defines the maximum for this fresh search. Set confirm_credit_spend only after that review.

​
Managed contact enrichment export

A managed contact enrichment export uses a batch_id. The batch remains appendable through airscale_add_contacts_to_enrichment_batch until the confirmed start. Review the approved contact count, work_email as the only enrichment, fields and format, and the maximum calculated as the approved contact count multiplied by up to 2 credits per contact. Review that additional maximum together with the cumulative workflow maximum. After reviewing the contact count and maximum, do not add more contacts. If the batch may have changed, rerun airscale_start_contact_enrichment_export with confirm_credit_spend set to false or omitted to obtain the current maximum, then review again. Only after approval should you set it to true. That confirmed start creates the export job and freezes the batch.

​
One export lifecycle

Both branches use one asynchronous lifecycle:
  1. Run the confirmed start once. An unconfirmed managed-contact maximum check does not create a job. Keep the returned export_id, and do not start a duplicate export while the job is queued or running.
  2. While status is queued or running, check status with the same export_id and respect the returned poll_after_seconds.
  3. When status is completed or failed, stop polling. Retrieve the file with the same export_id only after completion.

​
How credits work

  • Free operations include the credit check, planning, people count or company filter discovery, export status polling, and completed file retrieval.
  • Find People and Find Companies each cost 0.1 credit per returned row.
  • Company lookalikes costs 0.5 credits per unique returned company and reserves limit × 0.5 credits before searching.
  • Airsearch costs 1 credit per successful call.
  • The managed work-email-only contact enrichment phase costs up to 2 credits per contact.
  • Paid export starts fail closed until confirm_credit_spend is explicitly set after review.
For exact per-tool behavior, use the MCP tool catalog.
  1. Run airscale_check_credits for a free connection check.
  2. Verify the intended workspace before choosing a paid path.

​
People and company search/export

  1. Use a free count or filter discovery tool to plan the request.
  2. Run a bounded sample and inspect the returned shape.
  3. Review the workspace, results, and credit implications before continuing.
  4. For optional enrichment, request separate approval with its own maximum and updated cumulative spend.
  5. Before exporting, perform a renewed export review of the final query or filters, fields, format, max_rows, additional maximum credits, and cumulative workflow maximum.
  6. Set confirm_credit_spend only after approval, then start once.

​
Company lookalikes

Use airscale_company_lookalikes with 1–10 reference domains and an explicit small limit. All results return in one synchronous response. The tool shares 15 starts per rolling minute and 5 active searches per workspace with the API. Do not automatically retry; a lost response can still belong to a completed, charged search, and repeating it can cause another charge. See Company lookalikes for filters and total-result limits.

​
Managed contact enrichment/export

  1. Create a batch with airscale_create_contact_enrichment_batch.
  2. Use airscale_add_contacts_to_enrichment_batch while the batch is appendable before the confirmed start.
  3. Review the approved contact count, work_email, fields and format.
  4. Calculate the maximum from the approved contact count multiplied by up to 2 credits per contact, then review the additional maximum and cumulative workflow maximum.
  5. After reviewing the contact count and maximum, do not add more contacts.
  6. If the batch may have changed, rerun airscale_start_contact_enrichment_export with confirm_credit_spend set to false or omitted to obtain the current maximum, then review again.
  7. Only after approval should you set confirm_credit_spend to true. That confirmed start creates the export job and freezes the batch.

​
Finish either export

Start once. While status is queued or running, poll status for the same export job using the same export_id and returned poll_after_seconds. When status is completed or failed, stop polling; retrieve the file only after completion. Do not start the export again.

​
Security notes

  • OAuth keeps workspace credential resolution server-side; the hosted client does not receive or store the Airscale API key.
  • Header-capable developer clients should read AIRSCALE_API_KEY only from a protected runtime environment or secret manager.
  • Never put a literal key in prompts, tool arguments, source control, browser code, shell commands, or shell history.
  • Verify the intended workspace before paid actions because a credit balance alone does not identify it.
  • Review every paid tool name, scope, and maximum cost before approval.
  • If a developer API key is exposed or suspected compromised, rotate it immediately, update the protected secret, and reconnect every trusted client that used it.
  • Treat tokenized export URLs and exported files as sensitive. Never place them in prompts or logs, and follow your organization’s access, retention, and deletion rules.

​
Troubleshooting

For OAuth, restart browser sign-in and verify the intended workspace. For a header-capable developer client, confirm that its protected runtime can read the configured secret.
Confirm that the server URL is exactly https://mcp.airscale.io/mcp, then disconnect and reconnect so the client refreshes all 37 tools.
Run airscale_check_credits, reduce the paid scope, and review the maximum again. Do not repeatedly submit the same paid request.
Continue polling the same export_id at poll_after_seconds. Do not create a duplicate while its outcome is unknown.