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

# MCP setup

> Connect AIRCTRL to an MCP-compatible agent without placing credentials in prompts.

export function AirctrlWordmark() {
  return <span className="airctrl-wordmark" aria-label="AIRCTRL">
      <span aria-hidden="true" className="airctrl-wordmark-air">AIR</span>
      <span aria-hidden="true" className="airctrl-wordmark-ctrl">CTRL</span>
    </span>;
}

`@airctrl/mcp` runs locally on your machine or in infrastructure you control. It uses `@airctrl/sdk` for <AirctrlWordmark /> operations.

MCP does not inherit `airctrl login`. Configure its identity explicitly so an agent cannot silently reuse a terminal session. See [Combine <AirctrlWordmark /> tools](/guides/tool-workflows) for workflows that use both tools.

## Requirements

* Node.js available to the MCP client.
* A human PAT or one complete active Service Account credential.
* The <AirctrlWordmark /> API URL.
* A vault passphrase only in human mode when the agent is allowed to decrypt or change record values.

## Environment variables

| Variable                             |                                           Required | Purpose                                                        |
| ------------------------------------ | -------------------------------------------------: | -------------------------------------------------------------- |
| `AIRCTRL_MCP_API_URL`                |                       Always for a Service Account | API URL. Human mode defaults to `http://localhost:15430`.      |
| `AIRCTRL_MCP_API_TOKEN`              |                  Yes for <AirctrlWordmark /> calls | Human PAT or Service Account bearer.                           |
| `AIRCTRL_MCP_VAULT_PASSWORD`         |                       Only for record cryptography | Unlocks human cryptographic material locally.                  |
| `AIRCTRL_MCP_SA_CREDENTIAL_ID`       |                               Service Account mode | `credentialId` from the active credential bundle.              |
| `AIRCTRL_MCP_SA_CAP_PRIVATE_KEY_B64` |                               Service Account mode | Capability private key from the same bundle. It stays local.   |
| `AIRCTRL_MCP_SA_SERVICE_ACCOUNT_ID`  |                                           Optional | Service Account ID from the same bundle, used for diagnostics. |
| `AIRCTRL_MCP_KEY_*`                  | Only when adding or rotating a provider credential | Provider values read by variable name.                         |

Never place a PAT, passphrase, provider key or decrypted record in a prompt.

## Choose one identity

### Human

Create a PAT in **Settings > Access tokens**. Set `AIRCTRL_MCP_VAULT_PASSWORD` only when the agent may decrypt or change record values as you.

### Service Account

Create the Service Account, assign its custom roles and project access, and provision an active credential in the dashboard. Map these values from that same bundle:

```text theme={}
AIRCTRL_MCP_API_URL                 = bundle.baseUrl
AIRCTRL_MCP_API_TOKEN               = bundle.bearer
AIRCTRL_MCP_SA_CREDENTIAL_ID        = bundle.credentialId
AIRCTRL_MCP_SA_CAP_PRIVATE_KEY_B64  = bundle.capPrivateKeyB64
AIRCTRL_MCP_SA_SERVICE_ACCOUNT_ID   = bundle.serviceAccountId  # optional
```

Do not set `AIRCTRL_MCP_VAULT_PASSWORD` for a Service Account. MCP rejects partial bundles and mixed human/Service Account unlock material before connecting.

## Choose your MCP client

<AirctrlWordmark /> runs as a local `stdio` MCP server. Choose the guide for the AI client you use:

* [Claude Code](/mcp/claude-code)
* [Codex](/mcp/codex)
* [Cursor](/mcp/cursor)
* [VS Code](/mcp/vs-code)
* [Warp](/mcp/warp)

Each guide shows the file or interface that client uses, a read-only connection check, a natural request,
common failures, and how to remove <AirctrlWordmark /> again. <AirctrlWordmark /> does not currently publish the desktop extension
package required for a first-class Claude Desktop setup.

## Generic local server shape

Use the MCP client's normal server configuration shape:

```json theme={}
{
  "mcpServers": {
    "airctrl": {
      "command": "npx",
      "args": ["-y", "@airctrl/mcp"],
      "env": {
        "AIRCTRL_MCP_API_URL": "https://api.airctrl.dev",
        "AIRCTRL_MCP_API_TOKEN": "${AIRCTRL_TOKEN}",
        "AIRCTRL_MCP_VAULT_PASSWORD": "${AIRCTRL_VAULT_PASSPHRASE}"
      }
    }
  }
}
```

Your MCP client decides whether `${...}` values are expanded. If it does not support expansion, use its documented secret or environment configuration instead of committing credentials to the file.

Service Account example:

```json theme={}
{
  "mcpServers": {
    "airctrl-machine": {
      "command": "npx",
      "args": ["-y", "@airctrl/mcp"],
      "env": {
        "AIRCTRL_MCP_API_URL": "https://api.airctrl.dev",
        "AIRCTRL_MCP_API_TOKEN": "${AIRCTRL_SA_BEARER}",
        "AIRCTRL_MCP_SA_CREDENTIAL_ID": "${AIRCTRL_SA_CREDENTIAL_ID}",
        "AIRCTRL_MCP_SA_CAP_PRIVATE_KEY_B64": "${AIRCTRL_SA_CAP_PRIVATE_KEY_B64}",
        "AIRCTRL_MCP_SA_SERVICE_ACCOUNT_ID": "${AIRCTRL_SERVICE_ACCOUNT_ID}"
      }
    }
  }
}
```

## Provider credentials

Add provider values to the MCP server environment with an `AIRCTRL_MCP_KEY_*` name. Then tell the agent only the name.

```json theme={}
{
  "AIRCTRL_MCP_KEY_OPENAI_PRODUCTION": "${OPENAI_API_KEY}"
}
```

Example request:

> Add an OpenAI provider credential named "Production OpenAI". Read the key from `AIRCTRL_MCP_KEY_OPENAI_PRODUCTION`.

The tool validates the variable name and reads the value inside the local MCP process.

## Verify the connection

Ask:

> Show <AirctrlWordmark /> MCP status. Do not call any record tool.

The `airctrl_status` tool reports the API URL, the selected identity type and whether its credential is configured. It does not reveal credential values.

In human mode, then ask:

> List my <AirctrlWordmark /> accounts.

The server calls `list_accounts`.

In Service Account mode, `list_accounts` is intentionally unavailable. Verify a real assigned scope instead:

> List <AirctrlWordmark /> record metadata for project `<project-id>`. Do not decrypt values.

The server calls `list_records` and the API returns only records the Service Account may access.

## Agent safety

* Approve the smallest action needed.
* Give explicit account, project and resource IDs.
* Review write parameters before execution.
* Do not call `get_secret` or `get_all` unless the model may receive the plaintext.
* Keep Service Account credential lifecycle in the dashboard. MCP does not expose it.

See the complete [MCP tools](/mcp/tools) list.