MCP setup - AIRCTRL

@airctrl/mcp runs locally on your machine or in infrastructure you control. It uses @airctrl/sdk for operations. MCP does not inherit airctrl login. Configure its identity explicitly so an agent cannot silently reuse a terminal session. See Combine tools 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 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 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:

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

runs as a local stdio MCP server. Choose the guide for the AI client you use:

Each guide shows the file or interface that client uses, a read-only connection check, a natural request, common failures, and how to remove again. 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:

{
  "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:

{
  "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.

{
  "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 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 accounts.

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

List 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 list.

​Requirements

​Environment variables

​Choose one identity

​Human

​Service Account

​Choose your MCP client

​Generic local server shape

​Provider credentials

​Verify the connection

​Agent safety