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.

Groups and access material

These tools are human-only. Team+ and RBAC apply; Service Accounts cannot manage or join human groups. Read Groups and effective access before changing membership.

Tool	Inputs	Purpose
`list_groups`	`accountId`, `projectId`	List groups in the project context and their current grants.
`list_record_group_grants`	`accountId`, `recordId`	Read group sharing options and caller capabilities.
`create_group`	`accountId`, `projectId`, `name`; optional `description`	Create a reusable account group without granting a project role.
`update_group`	`accountId`, `groupId`, `name`; optional `description`	Replace name and description; omission clears description.
`delete_group`	`accountId`, `groupId`	Delete the group while preserving independent access paths.
`list_group_members`	`accountId`, `groupId`	List current members, not candidate users.
`add_group_member`	`accountId`, `groupId`, `userId`	Add membership across existing group grants.
`remove_group_member`	`accountId`, `groupId`, `userId`	Remove only this membership and reconcile effective access.
`grant_project_group`	`accountId`, `projectId`, `groupId`, `roleId`	Grant an existing delegable project role.
`revoke_project_group`	`accountId`, `projectId`, `groupId`, `roleId`	Revoke only this project/group/role assignment.
`reconcile_group_access`	`accountId`; optional `projectIds`	Attempt pending material repair with the configured local vault.

Membership, deletion and grant results are server snapshots, including changed, wrapper-deletion counts and per-resource changes. Check pending material and remaining paths; success is not proof that every recipient can decrypt. Reconciliation returns attempts in attemptedProjectIds, never a permission grant. Optional project IDs limit project repair, not pending direct group-record shares in the account. Missing holder material can remain pending. Never put a passphrase in a prompt; use the existing local MCP vault configuration.

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`; optional `environment`	Decrypt one General or selected Environment value locally.
`read_record`	`recordId`; optional `scope`, `environment`	Read selected record sections and only the selected secret value. `fields` returns its complete decrypted field map.
`get_all`	`projectId`; optional `environment`	Decrypt accessible General or selected Environment values 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`, `environment`, `tags`, `secretDueAt`, `rotationIntervalDays`, `idempotencyKey`	Encrypt and create a General record, or one Environment record with its selected value.
`set_secret`	`fields`; either `recordId` or `projectId`, `name`, `secretFormat`; optional `environment`, `changedFields`, `tags`, `secretDueAt`, `rotationIntervalDays`, `idempotencyKey`	Update one selected value 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`; optional `environment`	Change safe record metadata. Select an Environment when changing its due date or rotation interval.
`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`	Open an earlier version locally and append a new current version under the current data key. Human mode and local vault unlock required.
`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 the direct user grant; preserve independent access paths.
`revoke_record_service_account`	`recordId`, `serviceAccountId`	Remove one Service Account’s record access.
`revoke_record_group`	`recordId`, `groupId`	Remove the group grant; preserve independent access paths.

Record audit

Tool	Inputs	Purpose
`read_record_audit`	`recordId`; optional `limit`	Read audit events for one record.
`list_record_audit`	`recordId`; optional `cursor`, `action`, `actor`, `from`, `to`, `limit`, legacy `offset`	Read a stable filtered audit-event page.
`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`, `cursor`, `limit`, legacy `offset`	Read the record alert feed.
`list_record_access`	Optional `accountId`, `scopeType`, `scopeId`, `cursor`, `limit`, legacy `offset`, `actions`	Read the record access feed.

Ask an agent for a bounded page and keep the returned cursor opaque:

List the first 25 record.update audit events for record
00000000-0000-4000-8000-000000000020 where the actor contains "david".
Return pagination.next_cursor without decoding it.

MCP tool used: list_record_audit

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`, `credentialKind`	Read a provider value from an allowed environment variable and store it. `credentialKind` accepts `api_key`, `oauth`, `aws_sigv4`, or `gcp_sa`.
`list_provider_models`	`accountId`, `credentialId`	List models available through a provider credential, including official numeric rates, `displayText`, and context-tiered `rateCard` data.
`rotate_provider_key`	`accountId`, `credentialId`, `apiKeyEnv`	Replace a provider credential using an `AIRCTRL_MCP_KEY_*` environment variable; the raw key never enters the tool call.
`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`; optional `slug`, `credentialBindings`	Create a gateway, optionally with explicit credential/model bindings.
`setup_gateway`	`projectId`, `provider`, `apiKeyEnv`, `models`; optional `name`, `tokenName`, `baseUrlOverride`	Add or reuse a provider credential, validate and bind every live-catalog model, create a gateway, mint a token and return connection data.
`get_connection_config`	`gatewayId`	Return compatibility and native OpenAI, Anthropic, Gemini, Mistral, OpenRouter, HiTheo, Groq, Novita AI, Atlas Cloud, and xAI URLs, plus supported realtime WebSocket URLs.
`set_routing`	`accountId`, `gatewayId`; optional `name`, `isActive`, `attachCredentialId`, `modelIds`	Update gateway metadata and optionally attach one credential to several live-catalog models. `attachCredentialId` and `modelIds` are provided together.
`set_gateway_settings`	`accountId`, `gatewayId`; at least one optional settings field	Update limits, logging, guardrails or allowed models.
`detach_gateway_credential`	`accountId`, `gatewayId`, `credentialId`; optional `modelId`	With `modelId`, remove one exact model binding. Without it, detach every model for the credential. The credential is not revoked.
`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 `scopes`, `expiresInDays`, `principal`, `allowedModels`, `spendLimit`, `spendWindow`, `rateLimitPerMin`	Create a constrained 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`, `until`, `provider`, `model`, `status`, `statusClass`, `search`, `cursor`, `limit`, legacy `offset`	Read filtered request metadata for one gateway and search stored bodies when authorized.
`read_gateway_log`	`gatewayId`, `logId`	Read stored request and response bodies for one gateway log.
`read_gateway_key_access`	`gatewayId`; optional `outcome`, `since`, `until`, `limit`, `offset`	List provider credential access outcomes.
`list_usage_logs`	`projectId`; optional `since`, `until`, `provider`, `model`, `status`, `gatewayId`, `cursor`, `limit`, legacy `offset`	List usage across a project.
`read_usage_log`	`projectId`, `logId`	Read one project’s stored request and response bodies.
`read_usage_spend`	`projectId`; optional `gatewayId`	Compare spend with effective project or gateway limits.
`read_usage_metrics`	`projectId`; optional `since`, `until`, `bucket`, `gatewayId`, `provider`, `model`, `statusClass`, `search`	Read filterable project or gateway 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 is inclusive and until is exclusive.
read_record.scope accepts sections only: fields, meta, owner, access, or full. It does not select individual field names.
Omit environment to select General, or use development, staging, or production to select exactly that record value. The PAT or Service Account token must permit the selected scope; an absent value never falls back to General or another Environment.
get_secret, read_record with fields, and get_all return plaintext to the local MCP client. The model or agent can receive that plaintext; use these tools only when that exposure is approved.
Log pagination starts without a cursor. Continue with pagination.next_cursor, the same scope and the exact same filters. Cursors cannot be combined with legacy offset. 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

Read one Environment value locally

For a By Environment record, request one value explicitly:

Read only the Staging value of record
"00000000-0000-4000-8000-000000000020". Do not read General, Development
or Production. Use the value only for this approved task; do not repeat it
in your response.

MCP tool used: get_secret with environment: 'staging'

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". Set the service name to "Database"
and username to "app_user", then generate a 32-character password locally.
Before creating it, confirm the project ID, name, format and non-secret fields.
Never print the generated password.

MCP tool used: create_record

Create a generated Environment record

The same tool can create a single Staging value without inventing another record or exposing generated material in the prompt:

Create an SSH record named "Deployment key" in project
"00000000-0000-4000-8000-000000000010" for Staging only. Generate the key
locally with host "stage.example.invalid" and username "deploy". Show
the project, name, format and Environment before asking for my confirmation.
Do not print the generated private key.

MCP tool used: create_record with environment: 'staging' and generate: true

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

OAuth partner Apps

The MCP server has no OAuth App credential mode, authorization-code flow, or installation/protection lifecycle tools. Do not place OAuth client secrets, authorization codes, access tokens, or refresh tokens in MCP configuration or an agent conversation. Neither is a confidential partner token store, and a hosted MCP would violate the partner-backend boundary. Implement OAuth partner flows through direct HTTP/OpenAPI or OAuthPartnerClient in the partner’s confidential backend. See OAuth partner integrations, OAuth protocol, and OAuth protection API. MCP may manage ordinary gateways with a separately authorized human PAT; those tools do not act as an OAuth installation.

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

​Groups and access material

​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

​Read one Environment value locally

​Create a generated password record

​Create a generated Environment record

​Set up a gateway from an environment variable

​Review usage before changing limits

​Revoke a gateway token

​OAuth partner Apps

​Tool results

​Tool failures

​Short agent requests