Connect Airscale MCP to Claude

Connect Claude to your Airscale workspace through hosted remote OAuth where supported, or configure Claude Code with a protected environment-backed header.

MCP server URL

Use the official remote MCP endpoint exactly as shown:

https://mcp.airscale.io/mcp

What Claude can do with Airscale MCP

Airscale MCP gives Claude 37 typed tools that can:

Check the authorized workspace’s credit balance.
Search for people and companies, including with Leads Finder filters.
Find companies similar to reference domains with Company lookalikes.
Count matches and discover accepted filter values before a paid search.
Enrich work contact details and extract people or company profiles.
Find a company’s LinkedIn URL from its domain and list the people who liked or commented on a LinkedIn post.
Verify emails, check WhatsApp availability and US Do Not Call status, and look up a company’s Meta ads.
Run Airsearch web research.
Create downloadable people or company exports.

Managed large contact enrichment is work-email-only in its current phase. Review exact inputs and credit behavior in the MCP tool catalog.

Before you start

You need an Airscale account with access to the intended workspace, API access enabled, and an active workspace credential. Claude web and desktop clients can use remote OAuth in the browser where supported by the Claude account and client. Each hosted user signs in to Airscale and authorizes a workspace. Claude Code can instead use a protected authorization header sourced from an environment variable. Hosted OAuth and Claude Code header authentication are separate connection methods. Never put the credential in a prompt or MCP tool argument.

Claude web setup

Use the hosted connector flow that matches your Claude account. If availability or labels differ, check Anthropic’s current remote custom connector guide.

Individual Claude accounts

Individual Free, Pro, or Max accounts can add a custom connector directly. A Free account is limited to one custom connector.

Open connector settings

Sign in to Claude web or desktop and open Customize → Connectors. Use the current connectors or integrations settings if the label differs.

Add Airscale

Choose the control to add a custom connector, name it Airscale MCP, and enter https://mcp.airscale.io/mcp as the remote server URL.

Authorize your Airscale workspace

Continue to the browser sign-in, authenticate with Airscale, select the intended workspace, approve access, and return to Claude.

Enable the tools

Select Airscale MCP for a new conversation and confirm that Claude can see its tools.

Claude Team and Enterprise

For Claude Team or Enterprise, an Owner or Primary Owner must add Airscale through Custom → Web before members can connect.

Owner adds the organization connector

Open Organization settings → Connectors, choose Add, hover over Custom, select Web, and enter https://mcp.airscale.io/mcp. Add the connector to the organization.

Each member authorizes Airscale

Each member opens Customize → Connectors, finds Airscale MCP, clicks Connect, and authenticates with their own Airscale account in the browser.

Each member enables the tools

Select Airscale MCP and the tools needed for the conversation. Organization approval makes the connector available; it does not share an Owner’s Airscale authorization with members.

Claude Code setup

Load AIRSCALE_API_KEY through an OS or team secret manager or a protected runtime environment before starting Claude Code. Do not type a literal API key into a shell command or shell history. Create a project-scoped .mcp.json at the project root:

Project .mcp.json

{
  "mcpServers": {
    "airscale": {
      "type": "http",
      "url": "https://mcp.airscale.io/mcp",
      "headers": {
        "Authorization": "Bearer ${AIRSCALE_API_KEY}"
      }
    }
  }
}

The ${AIRSCALE_API_KEY} expression is resolved from the Claude Code process environment. Never replace it with a literal secret in .mcp.json; each developer supplies the environment value independently. From the project root, verify that Claude Code loaded the server:

claude mcp list

Inside Claude Code, run /mcp to inspect connection status and the available tools. See the official Claude Code MCP scope documentation before choosing a different scope; local and user configurations live in ~/.claude.json, not in the project file.

Recommended first prompts

The identities and domains below are synthetic.

Use airscale_check_credits to show my current Airscale credit balance. Do not call another tool.

This is the free connection test. A returned balance confirms tool discovery and authentication to an Airscale workspace without debiting credits, but it does not identify which workspace. Hosted users must verify the OAuth-selected workspace, and Claude Code users must verify which workspace owns the configured credential before paid actions.

Use Airscale MCP to count people named Taylor Example at northstar.example. Do not run a paid search.

Plan an Airscale search for up to five companies matching sample-company.test. Show the proposed Airscale tool, arguments, and maximum cost, then wait for my approval.

For a complete staged sequence, follow the safe MCP workflow.

Export behavior

A people or company export performs a fresh paid search from the final filters; it does not package the selected chat rows and may return different rows. Before approval, review the exact filters, fields, format, max_rows, additional maximum credits, and cumulative workflow maximum. An export has one asynchronous lifecycle: start the export once, check its status, then retrieve the file when it is ready. Reuse the same export_id and honor the returned poll_after_seconds. Do not start a duplicate export while the original job is queued or running.

Credits and confirmation

The credit check, people count, company filter-value discovery, export status, and export-file retrieval are free. Search and enrichment tools can consume credits; Airsearch costs 1 credit per successful call. Managed contact enrichment is work-email-only in its current phase. Paid export starts fail closed until confirm_credit_spend is explicitly true. Review Claude’s proposed tool, arguments, row limit, and maximum cost before confirming. An export can support up to 10,000 rows, but use the smallest limit that serves the task.

Refreshing tools

If Airscale tools are stale or missing, refresh or reconnect the hosted connector and start a new conversation. In Claude Code, verify the environment and server with claude mcp list, then use /mcp to inspect the refreshed connection.

Troubleshooting

Hosted connector controls are unavailable

Confirm that the Claude client and account support remote MCP connectors. In Team or Enterprise, ask an Owner or Primary Owner to add Airscale before each member connects their own account.

OAuth opens but the connection stays pending

Complete the Airscale browser sign-in, wait for the authorization confirmation, and return to Claude. Reconnect while signed in to the intended workspace if the state does not update.

Claude Code reports an authentication error

Confirm that the environment variable is available to the Claude Code process and that the project configuration uses the Bearer scheme. Do not print the value while debugging.

An export remains queued

Poll airscale_get_export_status with the same identifier and the returned poll_after_seconds. Do not create another paid job.

Security note

Hosted Claude users should authorize only the Airscale workspace they intend to use. Claude Code users should keep the environment value out of version control, prompts, and tool inputs. For either method, review every proposed paid action and remove access when it is no longer needed.

Need help?

Review the MCP tool catalog for exact schemas and credit behavior.
Use the safe MCP workflow before running a search or export.
Read the Airscale MCP server overview for authentication and security guidance.

​MCP server URL

​What Claude can do with Airscale MCP

​Before you start

​Claude web setup

​Individual Claude accounts

​Claude Team and Enterprise

​Claude Code setup

​Recommended first prompts

​Export behavior

​Credits and confirmation

​Refreshing tools

​Troubleshooting

​Security note

​Need help?