> ## 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 tools > Complete tool reference for the AIRCTRL MCP server. export function AirctrlWordmark() { return ; } MCP tools use `@airctrl/sdk`. Tool results contain structured JSON. Errors return safe codes and messages without exposing stored credentials. Use [MCP prompt cookbook](/mcp/prompts) for one prompt per tool. Use [MCP workflows](/mcp/workflows) for prompts that coordinate several tools safely. ## Identity availability A human PAT can use every API-backed tool on this page when RBAC permits it. Local helpers do not require API authorization. A Service Account sees only the tools that its API identity can actually use: | Service Account tool | Purpose | | ------------------------- | ----------------------------------------------------------------------------- | | `airctrl_status` | Confirm that MCP selected Service Account mode without revealing credentials. | | `list_records` | List record metadata granted through its custom role or direct record access. | | `get_secret` | Decrypt one accessible record locally. | | `read_record` | Read permitted sections of one accessible record. | | `get_all` | Decrypt accessible records in one project. | | `list_secret_types` | List record formats locally. | | `generate_secret` | Generate secret material locally without storing it. | | `list_providers` | List enabled AI providers. | | `get_connection_config` | Read connection details for one accessible gateway. | | `list_gateway_tokens` | List safe token metadata for one accessible gateway. | | `read_usage` | List request metadata for one accessible gateway. | | `read_gateway_log` | Read one accessible gateway log. | | `read_gateway_key_access` | Read provider-key access events for one accessible gateway. | All other tools are human-only and are not registered in Service Account mode. RBAC can still deny any listed operation when the Service Account lacks the required custom-role permission or project access. ## Status and context | Tool | Inputs | Purpose | | --------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- | | `airctrl_status` | None | Show API URL and whether authentication is configured. | | `list_accounts` | None | List accounts available to the configured human PAT. | | `list_projects` | `accountId`; optional `includeArchived` | List accessible projects in one account. | | `get_project` | `accountId`, `projectId` | Read one project. | | `create_project` | `accountId`, `name`; optional `description` | Create a project and make the caller Project Administrator. | | `update_project` | `accountId`, `projectId`, `name`, `description`, `isActive` | Replace project name, description and active state. | | `set_project_archive` | `accountId`, `projectId`, `archived` | Archive or restore one project. | ## Service Account metadata | Tool | Inputs | Purpose | | ----------------------- | ------------------------------- | -------------------------------------------------- | | `list_service_accounts` | `accountId` | List safe Service Account metadata in one account. | | `get_service_account` | `accountId`, `serviceAccountId` | Find one Service Account by ID. | These metadata tools are human-only. Service Account creation, state changes, credential lifecycle and identity rotation are not MCP tools. ## Record reading and creation | Tool | Inputs | Purpose | | ------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `list_records` | Optional `projectId`, `accountId`, `tab`, `includeArchived`, `limit`, `offset` | List accessible record metadata. | | `get_secret` | `recordId` | Decrypt one complete record locally. | | `read_record` | `recordId`; optional `scope`, `environment` | Read selected record sections. | | `get_all` | `projectId` | Decrypt every accessible record in one project. | | `list_secret_types` | None | List supported record formats and field definitions. | | `generate_secret` | `format`; optional `options` | Generate supported secret material locally without storing it. | | `create_record` | `projectId`, `name`, `secretFormat`; optional `fields`, `generate`, `options` | Encrypt and create a record from supplied or generated fields. | | `set_secret` | `fields`; either `recordId` or `projectId`, `name`, `secretFormat`; optional `changedFields` | Update by ID or create/upsert by project and name. Human-only. | ## Record lifecycle and sharing | Tool | Inputs | Purpose | | ------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------- | | `update_record_metadata` | `recordId`; at least one of `name`, `tags`, `secretDueAt`, `rotationIntervalDays` | Change safe record metadata. | | `set_record_archive` | `recordId`, `archived` | Archive or restore a record. | | `transfer_record_ownership` | `recordId`, `newOwnerUserId` | Transfer record ownership to an eligible user. | | `list_record_versions` | `recordId` | List record version history. | | `rollback_record` | `recordId`, `targetVersionId` | Restore an earlier encrypted version. | | `rotate_record` | `recordId` | Rotate the record key and encrypted value locally. | | `share_record_user` | `recordId`, `userId`; optional `permission` | Share a record with one user. | | `share_record_service_account` | `accountId`, `recordId`, `serviceAccountId` | Share a record with one Service Account. | | `share_record_group` | `recordId`, `groupId` | Share a record with a group. | | `revoke_record_user` | `recordId`, `userId` | Remove one user's record access. | | `revoke_record_service_account` | `recordId`, `serviceAccountId` | Remove one Service Account's record access. | | `revoke_record_group` | `recordId`, `groupId` | Remove a group's record access. | ## Record audit | Tool | Inputs | Purpose | | ----------------------- | -------------------------------------------------------------------------- | ----------------------------------- | | `read_record_audit` | `recordId`; optional `limit` | Read audit events for one record. | | `list_record_anomalies` | Optional `accountId`, `scopeType`, `scopeId` | List unusual record events. | | `list_record_activity` | `day`; optional `accountId`, `scopeType`, `scopeId` | Read one UTC day's record activity. | | `list_record_alerts` | Optional `accountId`, `scopeType`, `scopeId`, `limit`, `offset` | Read the record alert feed. | | `list_record_access` | Optional `accountId`, `scopeType`, `scopeId`, `limit`, `offset`, `actions` | Read the record access feed. | ## Providers and gateway setup | Tool | Inputs | Purpose | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_providers` | None | List enabled AI providers. | | `list_provider_credentials` | `accountId` | List safe provider credential metadata. | | `add_provider_key` | `accountId`, `providerId`, `apiKeyEnv`; optional `label`, `baseUrlOverride` | Read a provider value from an allowed environment variable and store it. | | `list_provider_models` | `accountId`, `credentialId` | List models available through a provider credential. | | `rotate_provider_key` | `accountId`, `credentialId`, `apiKey` | Replace a provider credential. Prefer the environment-backed setup flow when an agent is involved. | | `rename_provider_credential` | `accountId`, `credentialId`, `label` | Change a provider credential label. | | `revoke_provider_credential` | `accountId`, `credentialId` | Revoke a provider credential. | | `list_gateways` | `projectId` | List gateways in one project. | | `create_gateway` | `accountId`, `projectId`, `name` | Create a bare gateway without a provider key/model binding. | | `setup_gateway` | `projectId`, `provider`, `apiKeyEnv`, `defaultModel`; optional `name`, `tokenName`, `baseUrlOverride` | Add or reuse a provider credential, validate and bind the live-catalog model, create a gateway, mint a token and return connection data. | | `get_connection_config` | `gatewayId` | Return provider-compatible connection URLs for a gateway. | | `set_routing` | `accountId`, `gatewayId`; optional `attachCredentialId`, `defaultProviderId`, `defaultModel` with the required combinations described below | Attach one credential to one live-catalog model and optionally make that binding the default route. `defaultModel` is required with `attachCredentialId` or `defaultProviderId`. | | `set_gateway_settings` | `accountId`, `gatewayId`; at least one optional settings field | Update limits, logging, guardrails, caching or allowed models. | | `detach_gateway_credential` | `accountId`, `gatewayId`, `credentialId` | Detach a provider credential without revoking it. | | `delete_gateway` | `accountId`, `gatewayId` | Disable a gateway and revoke its tokens. | ## Gateway tokens | Tool | Inputs | Purpose | | ---------------------- | ---------------------------------------------------------- | ------------------------------------------------- | | `list_gateway_tokens` | `gatewayId` | List safe gateway token metadata. | | `create_gateway_token` | `accountId`, `gatewayId`, `name`; optional `expiresInDays` | Create a gateway token and return its value once. | | `rename_gateway_token` | `accountId`, `gatewayId`, `tokenId`, `name` | Change a gateway token label. | | `revoke_gateway_token` | `accountId`, `gatewayId`, `tokenId` | Stop a gateway token from authenticating. | | `delete_gateway_token` | `accountId`, `gatewayId`, `tokenId` | Delete gateway token metadata. | ## Logs, usage and OpenTelemetry | Tool | Inputs | Purpose | | ------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | `read_usage` | `gatewayId`; optional `since`, `limit` | Read request metadata for one gateway. | | `read_gateway_log` | `gatewayId`, `logId` | Read stored request and response bodies for one gateway log. | | `read_gateway_key_access` | `gatewayId`; optional `outcome`, `since`, `limit`, `offset` | List provider credential access outcomes. | | `list_usage_logs` | `projectId`; optional `since`, `provider`, `model`, `status`, `gatewayId`, `limit`, `offset` | List usage across a project. | | `read_usage_log` | `projectId`, `logId` | Read one project's stored request and response bodies. | | `read_usage_spend` | `projectId` | Compare spend with effective limits. | | `read_usage_metrics` | `projectId`; optional `since`, `bucket` | Read request, error, token, latency and spend metrics. | | `get_otel_export` | `accountId`, `gatewayId` | Read safe OpenTelemetry export settings. | | `set_otel_export` | `accountId`, `gatewayId`; optional export fields | Update OpenTelemetry export settings. | ## Input rules * IDs are UUID strings. Copy them from instead of asking an agent to guess them. * Dates and timestamps use ISO 8601. `day` uses `YYYY-MM-DD`; `since` accepts a complete timestamp. * Pagination starts at `offset: 0`. Keep `limit` small when an agent only needs a summary. * `accountId` selects the account. It does not grant access to it. * `projectId`, `recordId`, `gatewayId`, `credentialId` and `tokenId` select resources. still checks RBAC and resource access. * Optional booleans must be real JSON booleans such as `true`, not strings such as `"true"`. * Tools that create credentials or tokens can return a value only once. Save it immediately in an approved destination. For write or destructive operations, ask the agent to repeat the target IDs and intended change before it calls the tool. This makes accidental changes easier to catch. ## Complete workflow examples ### Inspect a project without decrypting records
`list_records` returns safe metadata. It does not decrypt secret fields.
```text theme={} Show the first 25 active records in project "00000000-0000-4000-8000-000000000010". Return only record names, formats, tags and IDs. Do not decrypt any values. ```
**MCP tool used:** `list_records`
### Read one secret locally
The MCP server obtains encrypted data through the SDK and decrypts it on the machine where MCP is running. The agent can still receive the plaintext result, so only use this tool in a trusted agent session.
```text theme={} Read record "00000000-0000-4000-8000-000000000020" locally. Use its value only for this task. Do not print it, log it or include it in your final response. ```
**MCP tool used:** `get_secret`
### Create a generated password record
`create_record` encrypts the generated fields locally before sending the record to .
```text theme={} Create a password record named "Production database password" in project "00000000-0000-4000-8000-000000000010" and generate a 32-character value locally. Before creating it, confirm the project ID, name and format. Never print the generated password. ```
**MCP tool used:** `create_record`
### Set up a gateway from an environment variable
The MCP process reads `AIRCTRL_MCP_KEY_OPENAI_PRODUCTION`; the model does not need the provider key in the prompt. The returned gateway token is shown only once.
```text theme={} Set up an OpenAI gateway named "Production gateway" in project "00000000-0000-4000-8000-000000000010". Read the provider key from "AIRCTRL_MCP_KEY_OPENAI_PRODUCTION", use "gpt-5" by default, and name the first gateway token "Local development". Show the proposed details and wait for my confirmation. Never print the environment variable value. ```
**MCP tool used:** `setup_gateway`
### Review usage before changing limits
This separates a read-only review from the later write.
```text theme={} Review current spend and request rates for project "00000000-0000-4000-8000-000000000010". Propose exact new limits, but do not change any gateway setting until I approve those values. ```
**MCP tools used:** `read_usage_spend`, `read_usage_metrics`, `set_gateway_settings`
### Revoke a gateway token
Revocation takes effect immediately. Listing a token never returns its secret value.
```text theme={} List tokens for gateway 00000000-0000-4000-8000-000000000030. Find the token named "Old laptop". Show its ID and status, then wait for confirmation. After confirmation, revoke only that token and report its final status. ```
**MCP tools used:** `list_gateway_tokens`, `revoke_gateway_token`
## Tool results API-backed tools return structured JSON from `@airctrl/sdk`. Read tools return the requested resource, list tools return arrays or paginated data, and write tools return the new or updated resource. One-time credentials are the exception: their plaintext is present only in the successful creation result. Local helpers behave differently: | Tool | Result | | ------------------- | ---------------------------------------------------------------------------------------------------- | | `airctrl_status` | Selected API URL, identity mode and configuration status; never credentials. | | `list_secret_types` | Supported secret formats and their field definitions. | | `generate_secret` | Generated secret fields in memory; nothing is stored until another tool creates or updates a record. | ## Tool failures An MCP failure includes a safe code and explanation. The tool does not return a successful result when the API denied the operation. | Failure | Meaning | Next action | | --------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------- | | Invalid input | A required ID or field is missing or malformed. | Correct the tool arguments. | | `service_account_not_supported` | The selected Service Account identity cannot use this tool. | Use a human PAT for an approved human-only operation. | | `not_authorized` or `insufficient_permission` | The identity lacks the required role or resource access. | Change access in the web app; do not retry unchanged. | | Resource not found | The ID is wrong, unavailable or hidden from the identity. | Recheck the ID and account or project context. | | `rate_limited` | Too many requests were made. | Wait and retry with a bounded backoff. | Never ask an agent to work around an authorization failure by trying unrelated accounts, projects or IDs. ## Short agent requests ```text theme={} List the projects in account 00000000-0000-4000-8000-000000000001. Do not create or update anything. ``` ```text theme={} Create a gateway in project 00000000-0000-4000-8000-000000000010. Use the OpenAI key stored in AIRCTRL_MCP_KEY_OPENAI_PRODUCTION. Before executing, show me the project ID, provider, gateway name and requested token limits. ``` ```text theme={} Show record metadata for project 00000000-0000-4000-8000-000000000010. Do not decrypt record values. ```