> ## 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.

# Connect Airscale MCP to Claude

> Connect Claude clients to Airscale with hosted OAuth or a protected Claude Code authorization header.

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:

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

## What Claude can do with Airscale MCP

Airscale MCP gives Claude 41 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](/mcp/tools).

## 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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Individual Claude accounts

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

**1. 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.

**2. 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.

**3. Authorize your Airscale workspace**

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

**4. 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.

**1. 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.

**2. Each member authorizes Airscale**

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

**3. 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:

```json Project .mcp.json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude mcp list
```

Inside Claude Code, run `/mcp` to inspect connection status and the available tools. See the official [Claude Code MCP scope documentation](https://code.claude.com/docs/en/mcp) 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](/mcp/how-to-use-the-airscale-mcp.md).

## 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](/mcp/tools) for exact schemas and credit behavior.
* Use the [safe MCP workflow](/mcp/how-to-use-the-airscale-mcp.md) before running a search or export.
* Read the [Airscale MCP server overview](/mcp/airscale-mcp-server.md) for authentication and security guidance.


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