MCP tools - AIRCTRL

MCP tools use @airctrl/sdk. Tool results contain structured JSON. Errors return safe codes and messages without exposing stored credentials. Use MCP prompt cookbook for one prompt per tool. Use 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.

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.

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.

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 .

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.

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.

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.

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

List the projects in account 00000000-0000-4000-8000-000000000001.
Do not create or update anything.

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.

Show record metadata for project 00000000-0000-4000-8000-000000000010.
Do not decrypt record values.

​Identity availability

​Status and context

​Service Account metadata

​Record reading and creation

​Record lifecycle and sharing

​Record audit

​Providers and gateway setup

​Gateway tokens

​Logs, usage and OpenTelemetry

​Input rules

​Complete workflow examples

​Inspect a project without decrypting records

​Read one secret locally

​Create a generated password record

​Set up a gateway from an environment variable

​Review usage before changing limits

​Revoke a gateway token

​Tool results

​Tool failures

​Short agent requests