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

# Airscale MCP Server

> Connect Airscale to your AI assistant and prospect without leaving the chat.

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

## MCP server URL

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://mcp.airscale.io/mcp
```

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

* [ChatGPT setup guide](/mcp/connect-airscale-mcp-to-chatgpt.md)
* [Claude setup guide](/mcp/connect-airscale-mcp-to-claude.md)
* [Airscale MCP workflow](/mcp/how-to-use-the-airscale-mcp.md)

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](/mcp/tools) is the schema reference for all 41 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](/mcp/tools).

## Recommended workflow

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](/api-reference/company-lookalikes.md) 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

> **The client cannot authenticate**
>
> 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.

> **The Airscale tools do not appear**
>
> Confirm that the server URL is exactly `https://mcp.airscale.io/mcp`, then disconnect and reconnect so the client refreshes all 41 tools.

> **A request reports insufficient credits**
>
> Run `airscale_check_credits`, reduce the paid scope, and review the maximum again. Do not repeatedly submit the same paid request.

> **An export is still running**
>
> Continue polling the same `export_id` at `poll_after_seconds`. Do not create a duplicate while its outcome is unknown.


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