MCP and agents

Airscale MCP Server

Connect Airscale to your AI assistant and prospect without leaving the chat. Airscale MCP lets supported assistants search for people and companies, enrich contacts, check credits, run Airsearch, and export results as downloadable CSV or JSONL files from a single conversation.

MCP server URL

Use this remote MCP server URL:

https://mcp.airscale.io/mcp

This is the official Airscale MCP endpoint. Use it when ChatGPT, Claude, Claude Code, Cursor, Windsurf, or another MCP-compatible client asks for a remote MCP server URL.

For OAuth-based clients such as ChatGPT custom MCP apps and Claude web connectors, do not paste an Airscale API key into the assistant. Sign in with Airscale in the browser instead.

The selected Airscale workspace still needs API access enabled and an active Airscale API key. OAuth resolves that workspace API key behind the scenes when tools run.

For Claude Team and Enterprise accounts, an Owner or Primary Owner must add Airscale MCP to the organization before members can connect it. Members then authenticate with their own Airscale account.

Getting started

Open your AI assistant's connector or MCP settings and add a custom remote MCP connector.

Paste the Airscale MCP server URL:

https://mcp.airscale.io/mcp

If your AI client supports OAuth, you will be redirected to sign in with your Airscale account in the browser. Authorize access, close the browser tab after the success page, and return to your AI assistant.

If your AI client does not support OAuth, use header-based setup with your Airscale API key.

Claude Code:

claude mcp add --transport http airscale https://mcp.airscale.io/mcp \
  --header "Authorization: Bearer your_airscale_api_key"

Generic MCP client configuration:

{
  "mcpServers": {
    "airscale": {
      "url": "https://mcp.airscale.io/mcp",
      "headers": {
        "Authorization": "Bearer your_airscale_api_key"
      }
    }
  }
}

For OAuth-based clients such as Claude web or ChatGPT custom MCP apps, do not paste an API key. Airscale handles authentication in the browser.

Setup walkthroughs

Need a step-by-step guide for your AI assistant?

• Connect Airscale MCP to Claude

• Connect Airscale MCP to ChatGPT

What you can do

Check credits

Ask your assistant to check the credits available in your Airscale workspace.

Check my Airscale credits.

This is the safest first test after connecting the MCP server. If the assistant returns your balance, the connector is authenticated and ready.

Search for people

Use natural language or structured filters to find people by name, job title, company, location, or keyword.

Find people with VP Sales or Head of Sales titles in France.

For large prospecting workflows, start with a count or a narrow search before exporting. People search supports pagination, but the MCP export tools are the right way to retrieve thousands of rows.

Search for companies

Search companies by firmographic, location, event, intent, technology, and website keyword filters. You can also ask the assistant to discover accepted filter values before running a search.

Find software companies in Germany with 51 to 200 employees.

Show me accepted industry values for Find Companies matching "software".

Enrich contacts and profiles

Airscale MCP exposes the core enrichment tools backed by the Airscale public API. You can find professional emails, bulk emails, mobile phones, personal emails, LinkedIn profile URLs, person profiles, company profiles, and reverse lookups from email or phone.

Find the professional email for this LinkedIn profile.

Enrich these 20 LinkedIn profiles with mobile phone numbers.

Managed large contact-enrichment exports currently support work-email enrichment. Phone, personal email, and profile enrichment are available through their respective MCP tools.

For paid enrichment, review what the assistant is about to run before approving the tool call.

Run AI web research

Use Airsearch to ask a natural-language research question and optionally extract structured fields.

Research this company and return its main product, target market, and latest funding news.

Airsearch is useful when the answer is not a simple database lookup and needs web research.

Export people or companies

Use export tools when you want a file, especially for hundreds or thousands of rows. Exports are asynchronous jobs: the assistant starts the job, polls status, then returns a download link when the file is ready.

Export up to 5,000 matching people as CSV.

Export these company results as JSONL with name, domain, website, cityName, and employeeRange.

Export tools do not stream thousands of rows into the chat. They write the file in Airscale's Cloudflare infrastructure and return compact metadata.

Export metadata

Export status and file tools may return:

• export_id

• status

• status_message

• progress_message

• poll_after_seconds

• rows_written

• pages_fetched

• total_estimate

• estimated_max_credits

• actual_credits

• download_url when complete

Large exports can take several minutes. If status says queued, follow status_message and poll again after poll_after_seconds.

How credits work

Airscale MCP uses the same credit behavior as the Airscale public API.

The live Airscale MCP server currently exposes 22 tools: 15 core public API tools, 4 people/company export tools, and 3 managed contact-enrichment batch/export tools.

Free tools

These MCP tools do not charge credits:

• airscale_check_credits

• airscale_count_find_people

• airscale_find_companies_filter_values

• airscale_create_contact_enrichment_batch

• airscale_add_contacts_to_enrichment_batch

• airscale_get_export_status

• airscale_get_export_file

Use them to validate the connection, estimate audience size, discover valid filters, create managed batches, and retrieve export status or files.

Search and enrichment

Search and enrichment through MCP use the same Airscale credit behavior as the public API.

• airscale_find_people costs 0.1 credits per returned lead.

• airscale_find_companies costs 0.1 credits per returned company.

• airscale_airsearch costs 1 credit per call.

• Email, phone, profile, reverse lookup, and other enrichment tools follow their Airscale API pricing.

• Managed work-email contact enrichment exports cost up to 2 credits per contact, based on work emails found.

Your AI assistant may ask for approval before calling tools, depending on the client. Review the proposed action before approving paid requests.

Exports

People and company exports are paid because the worker pages through the paid search endpoints to generate the file.

Before an export starts, the tool requires explicit confirmation with:

{ "confirm_credit_spend": true }

The response includes:

• estimated_max_credits: maximum possible spend based on max_rows

• actual_credits: final spend based on rows actually written

For example, exporting 10,000 people or companies has an estimated maximum of 1,000 credits at 0.1 credits per row. If only 8,847 rows are available, the completed job reports 884.7 actual credits.

Recommended workflow

1. Check credits.

2. Use free count or filter discovery where available.

3. Run a small search to inspect result quality.

4. Refine filters with the assistant.

5. Start an export only when the target list looks right.

6. Poll export status until completed.

7. Download the CSV or JSONL file and import it into your CRM or outreach workflow.

Security notes

Airscale MCP never accepts API keys as tool arguments.

OAuth clients authenticate in the browser. Header-based clients send the API key as an HTTP authorization header.

Normal tool calls forward the authenticated Airscale API key upstream without storing it. Async export jobs store only a short-lived encrypted credential until the job completes or fails, then remove it from job state.

Export status and file lookup are scoped to the user or workspace that created the job. The generated download URL is protected by a short-lived token, so treat it like a temporary secret and do not share it publicly.

Troubleshooting

The connection works but nothing happens

Start with:

Check my Airscale credits.

If the assistant returns your balance, the connector is connected correctly.

The browser sign-in completed but the AI looks stuck

Some clients do not automatically close the sign-in tab. Close the tab manually after the confirmation page, then return to your AI assistant.

Authentication succeeds but tools fail

Check the selected Airscale workspace:

• API access must be enabled.

• The workspace must have an active Airscale API key.

• The authenticated user must have access to that workspace.

• The workspace must have enough credits for paid tools.

OAuth signs the user in, but tool calls still depend on the workspace API key that Airscale resolves server-side.

Claude says I cannot add the connector

On Claude Team and Enterprise plans, individual members usually cannot add custom remote MCP connectors directly. Ask an Owner or Primary Owner to add Airscale MCP to the organization with this URL:

https://mcp.airscale.io/mcp

After that, connect it from Customize > Connectors and authenticate with Airscale.

The assistant cannot find Airscale tools

Make sure the Airscale connector is enabled in the current conversation. Some clients require enabling connectors in each new chat.

If Airscale recently added tools, refresh the connector or reconnect it so the client reloads the tool list.

Export status shows queued and 0 rows

This can be normal for large exports. The queue may need a short time to start, and KV-backed status can be eventually consistent. Follow status_message and poll again after poll_after_seconds.

Do not start a duplicate export unless you intentionally want another paid job.

Export is completed but no file is visible

Ask the assistant to call:

airscale_get_export_file

Use the same export_id. Status polling confirms progress; the file tool returns the final download URL.

Not getting enough results

Try broader filters first, then narrow down. Use standard job title, industry, company size, location, and keyword language.

For Find Companies, use airscale_find_companies_filter_values to discover valid values for filters such as industry, city, region, topics, and tech stack.