@airctrl/mcp 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1721 -0
- package/dist/config.js +78 -0
- package/dist/index.js +32 -0
- package/dist/tools.js +955 -0
- package/package.json +47 -0
package/README.md
ADDED
|
@@ -0,0 +1,1721 @@
|
|
|
1
|
+
# @airctrl/mcp
|
|
2
|
+
|
|
3
|
+
Local/self-hosted Model Context Protocol server for AIRCTRL records, projects, gateways and usage workflows.
|
|
4
|
+
|
|
5
|
+
[Documentation](https://docs.airctrl.dev) · [AIRCTRL](https://airctrl.dev) · [Support](https://docs.airctrl.dev/reference/errors)
|
|
6
|
+
|
|
7
|
+
> This README is generated from AIRCTRL's verified public documentation. The HTTP API is the capability source of truth; SDK, CLI and MCP are thin bindings over that contract.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npx --yes @airctrl/mcp
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Requires Node.js 22.x.
|
|
16
|
+
|
|
17
|
+
## MCP setup
|
|
18
|
+
|
|
19
|
+
`@airctrl/mcp` runs locally on your machine or in infrastructure you control. It uses `@airctrl/sdk` for AIRCTRL operations.
|
|
20
|
+
|
|
21
|
+
MCP does not inherit `airctrl login`. Configure its identity explicitly so an agent cannot silently reuse a terminal session. See [Combine AIRCTRL tools](https://docs.airctrl.dev/guides/tool-workflows) for workflows that use both tools.
|
|
22
|
+
|
|
23
|
+
### Requirements
|
|
24
|
+
|
|
25
|
+
- Node.js 22.x available to the MCP client.
|
|
26
|
+
- A human PAT or one complete active Service Account credential.
|
|
27
|
+
- The AIRCTRL API URL.
|
|
28
|
+
- A vault passphrase only in human mode when the agent is allowed to decrypt or change record values.
|
|
29
|
+
|
|
30
|
+
### Environment variables
|
|
31
|
+
|
|
32
|
+
| Variable | Required | Purpose |
|
|
33
|
+
|---|---:|---|
|
|
34
|
+
| `AIRCTRL_MCP_API_URL` | Always for a Service Account | API URL. Human mode defaults to `http://localhost:15430`. |
|
|
35
|
+
| `AIRCTRL_MCP_API_TOKEN` | Yes for AIRCTRL calls | Human PAT or Service Account bearer. |
|
|
36
|
+
| `AIRCTRL_MCP_VAULT_PASSWORD` | Only for record cryptography | Unlocks human cryptographic material locally. |
|
|
37
|
+
| `AIRCTRL_MCP_SA_CREDENTIAL_ID` | Service Account mode | `credentialId` from the active credential bundle. |
|
|
38
|
+
| `AIRCTRL_MCP_SA_CAP_PRIVATE_KEY_B64` | Service Account mode | Capability private key from the same bundle. It stays local. |
|
|
39
|
+
| `AIRCTRL_MCP_SA_SERVICE_ACCOUNT_ID` | Optional | Service Account ID from the same bundle, used for diagnostics. |
|
|
40
|
+
| `AIRCTRL_MCP_KEY_*` | Only when adding or rotating a provider credential | Provider values read by variable name. |
|
|
41
|
+
|
|
42
|
+
Never place a PAT, passphrase, provider key or decrypted record in a prompt.
|
|
43
|
+
|
|
44
|
+
### Choose one identity
|
|
45
|
+
|
|
46
|
+
#### Human
|
|
47
|
+
|
|
48
|
+
Create a PAT in **Settings > Access tokens**. Set `AIRCTRL_MCP_VAULT_PASSWORD` only when the agent may decrypt or change record values as you.
|
|
49
|
+
|
|
50
|
+
#### Service Account
|
|
51
|
+
|
|
52
|
+
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:
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
AIRCTRL_MCP_API_URL = bundle.baseUrl
|
|
56
|
+
AIRCTRL_MCP_API_TOKEN = bundle.bearer
|
|
57
|
+
AIRCTRL_MCP_SA_CREDENTIAL_ID = bundle.credentialId
|
|
58
|
+
AIRCTRL_MCP_SA_CAP_PRIVATE_KEY_B64 = bundle.capPrivateKeyB64
|
|
59
|
+
AIRCTRL_MCP_SA_SERVICE_ACCOUNT_ID = bundle.serviceAccountId # optional
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Do not set `AIRCTRL_MCP_VAULT_PASSWORD` for a Service Account. MCP rejects partial bundles and mixed human/Service Account unlock material before connecting.
|
|
63
|
+
|
|
64
|
+
### Choose your MCP client
|
|
65
|
+
|
|
66
|
+
AIRCTRL runs as a local `stdio` MCP server. Choose the guide for the AI client you use:
|
|
67
|
+
|
|
68
|
+
- [Claude Code](https://docs.airctrl.dev/mcp/claude-code)
|
|
69
|
+
- [Codex](https://docs.airctrl.dev/mcp/codex)
|
|
70
|
+
- [Cursor](https://docs.airctrl.dev/mcp/cursor)
|
|
71
|
+
- [VS Code](https://docs.airctrl.dev/mcp/vs-code)
|
|
72
|
+
- [Warp](https://docs.airctrl.dev/mcp/warp)
|
|
73
|
+
|
|
74
|
+
Each guide shows the file or interface that client uses, a read-only connection check, a natural request,
|
|
75
|
+
common failures, and how to remove AIRCTRL again. AIRCTRL does not currently publish the desktop extension
|
|
76
|
+
package required for a first-class Claude Desktop setup.
|
|
77
|
+
|
|
78
|
+
### Generic local server shape
|
|
79
|
+
|
|
80
|
+
Use the MCP client's normal server configuration shape:
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"mcpServers": {
|
|
85
|
+
"airctrl": {
|
|
86
|
+
"command": "npx",
|
|
87
|
+
"args": ["-y", "@airctrl/mcp"],
|
|
88
|
+
"env": {
|
|
89
|
+
"AIRCTRL_MCP_API_URL": "https://api.airctrl.dev",
|
|
90
|
+
"AIRCTRL_MCP_API_TOKEN": "${AIRCTRL_TOKEN}",
|
|
91
|
+
"AIRCTRL_MCP_VAULT_PASSWORD": "${AIRCTRL_VAULT_PASSPHRASE}"
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
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.
|
|
99
|
+
|
|
100
|
+
Service Account example:
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"mcpServers": {
|
|
105
|
+
"airctrl-machine": {
|
|
106
|
+
"command": "npx",
|
|
107
|
+
"args": ["-y", "@airctrl/mcp"],
|
|
108
|
+
"env": {
|
|
109
|
+
"AIRCTRL_MCP_API_URL": "https://api.airctrl.dev",
|
|
110
|
+
"AIRCTRL_MCP_API_TOKEN": "${AIRCTRL_SA_BEARER}",
|
|
111
|
+
"AIRCTRL_MCP_SA_CREDENTIAL_ID": "${AIRCTRL_SA_CREDENTIAL_ID}",
|
|
112
|
+
"AIRCTRL_MCP_SA_CAP_PRIVATE_KEY_B64": "${AIRCTRL_SA_CAP_PRIVATE_KEY_B64}",
|
|
113
|
+
"AIRCTRL_MCP_SA_SERVICE_ACCOUNT_ID": "${AIRCTRL_SERVICE_ACCOUNT_ID}"
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Provider credentials
|
|
121
|
+
|
|
122
|
+
Add provider values to the MCP server environment with an `AIRCTRL_MCP_KEY_*` name. Then tell the agent only the name.
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{
|
|
126
|
+
"AIRCTRL_MCP_KEY_OPENAI_PRODUCTION": "${OPENAI_API_KEY}"
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Example request:
|
|
131
|
+
|
|
132
|
+
> Add an OpenAI provider credential named "Production OpenAI". Read the key from `AIRCTRL_MCP_KEY_OPENAI_PRODUCTION`.
|
|
133
|
+
|
|
134
|
+
The tool validates the variable name and reads the value inside the local MCP process.
|
|
135
|
+
|
|
136
|
+
### Verify the connection
|
|
137
|
+
|
|
138
|
+
Ask:
|
|
139
|
+
|
|
140
|
+
> Show AIRCTRL MCP status. Do not call any record tool.
|
|
141
|
+
|
|
142
|
+
The `airctrl_status` tool reports the API URL, the selected identity type and whether its credential is configured. It does not reveal credential values.
|
|
143
|
+
|
|
144
|
+
In human mode, then ask:
|
|
145
|
+
|
|
146
|
+
> List my AIRCTRL accounts.
|
|
147
|
+
|
|
148
|
+
The server calls `list_accounts`.
|
|
149
|
+
|
|
150
|
+
In Service Account mode, `list_accounts` is intentionally unavailable. Verify a real assigned scope instead:
|
|
151
|
+
|
|
152
|
+
> List AIRCTRL record metadata for project `<project-id>`. Do not decrypt values.
|
|
153
|
+
|
|
154
|
+
The server calls `list_records` and the API returns only records the Service Account may access.
|
|
155
|
+
|
|
156
|
+
### Agent safety
|
|
157
|
+
|
|
158
|
+
- Approve the smallest action needed.
|
|
159
|
+
- Give explicit account, project and resource IDs.
|
|
160
|
+
- Review write parameters before execution.
|
|
161
|
+
- Do not call `get_secret` or `get_all` unless the model may receive the plaintext.
|
|
162
|
+
- Keep Service Account credential lifecycle in the dashboard. MCP does not expose it.
|
|
163
|
+
|
|
164
|
+
See the complete [MCP tools](https://docs.airctrl.dev/mcp/tools) list.
|
|
165
|
+
## MCP tools
|
|
166
|
+
|
|
167
|
+
AIRCTRL MCP tools use `@airctrl/sdk`. Tool results contain structured JSON. Errors return safe codes and messages without exposing stored credentials.
|
|
168
|
+
|
|
169
|
+
Use [MCP prompt cookbook](https://docs.airctrl.dev/mcp/prompts) for one prompt per tool. Use
|
|
170
|
+
[MCP workflows](https://docs.airctrl.dev/mcp/workflows) for prompts that coordinate several tools safely.
|
|
171
|
+
|
|
172
|
+
### Identity availability
|
|
173
|
+
|
|
174
|
+
A human PAT can use every API-backed tool on this page when RBAC permits it. Local helpers do not
|
|
175
|
+
require API authorization. A Service Account sees only the tools that its API identity can actually use:
|
|
176
|
+
|
|
177
|
+
| Service Account tool | Purpose |
|
|
178
|
+
|---|---|
|
|
179
|
+
| `airctrl_status` | Confirm that MCP selected Service Account mode without revealing credentials. |
|
|
180
|
+
| `list_records` | List record metadata granted through its custom role or direct record access. |
|
|
181
|
+
| `get_secret` | Decrypt one accessible record locally. |
|
|
182
|
+
| `read_record` | Read permitted sections of one accessible record. |
|
|
183
|
+
| `get_all` | Decrypt accessible records in one project. |
|
|
184
|
+
| `list_secret_types` | List record formats locally. |
|
|
185
|
+
| `generate_secret` | Generate secret material locally without storing it. |
|
|
186
|
+
| `list_providers` | List enabled AI providers. |
|
|
187
|
+
| `get_connection_config` | Read connection details for one accessible gateway. |
|
|
188
|
+
| `list_gateway_tokens` | List safe token metadata for one accessible gateway. |
|
|
189
|
+
| `read_usage` | List request metadata for one accessible gateway. |
|
|
190
|
+
| `read_gateway_log` | Read one accessible gateway log. |
|
|
191
|
+
| `read_gateway_key_access` | Read provider-key access events for one accessible gateway. |
|
|
192
|
+
|
|
193
|
+
All other tools are human-only and are not registered in Service Account mode. RBAC can still deny
|
|
194
|
+
any listed operation when the Service Account lacks the required custom-role permission or project access.
|
|
195
|
+
|
|
196
|
+
### Status and context
|
|
197
|
+
|
|
198
|
+
| Tool | Inputs | Purpose |
|
|
199
|
+
|---|---|---|
|
|
200
|
+
| `airctrl_status` | None | Show API URL and whether authentication is configured. |
|
|
201
|
+
| `list_accounts` | None | List accounts available to the configured human PAT. |
|
|
202
|
+
| `list_projects` | `accountId`; optional `includeArchived` | List accessible projects in one account. |
|
|
203
|
+
| `get_project` | `accountId`, `projectId` | Read one project. |
|
|
204
|
+
| `create_project` | `accountId`, `name`; optional `description` | Create a project and make the caller Project Administrator. |
|
|
205
|
+
| `update_project` | `accountId`, `projectId`, `name`, `description`, `isActive` | Replace project name, description and active state. |
|
|
206
|
+
| `set_project_archive` | `accountId`, `projectId`, `archived` | Archive or restore one project. |
|
|
207
|
+
|
|
208
|
+
### Service Account metadata
|
|
209
|
+
|
|
210
|
+
| Tool | Inputs | Purpose |
|
|
211
|
+
|---|---|---|
|
|
212
|
+
| `list_service_accounts` | `accountId` | List safe Service Account metadata in one account. |
|
|
213
|
+
| `get_service_account` | `accountId`, `serviceAccountId` | Find one Service Account by ID. |
|
|
214
|
+
|
|
215
|
+
These metadata tools are human-only. Service Account creation, state changes, credential lifecycle and identity rotation are not MCP tools.
|
|
216
|
+
|
|
217
|
+
### Record reading and creation
|
|
218
|
+
|
|
219
|
+
| Tool | Inputs | Purpose |
|
|
220
|
+
|---|---|---|
|
|
221
|
+
| `list_records` | Optional `projectId`, `accountId`, `tab`, `includeArchived`, `limit`, `offset` | List accessible record metadata. |
|
|
222
|
+
| `get_secret` | `recordId` | Decrypt one complete record locally. |
|
|
223
|
+
| `read_record` | `recordId`; optional `scope`, `environment` | Read selected record sections. `fields` returns the complete decrypted field map. |
|
|
224
|
+
| `get_all` | `projectId` | Decrypt every accessible record in one project. |
|
|
225
|
+
| `list_secret_types` | None | List supported record formats and field definitions. |
|
|
226
|
+
| `generate_secret` | `format`; optional `options` | Generate supported secret material locally without storing it. |
|
|
227
|
+
| `create_record` | `projectId`, `name`, `secretFormat`; optional `fields`, `generate`, `options`, `tags`, `secretDueAt`, `rotationIntervalDays`, `idempotencyKey` | Encrypt and create a record from supplied or generated fields. |
|
|
228
|
+
| `set_secret` | `fields`; either `recordId` or `projectId`, `name`, `secretFormat`; optional `changedFields`, `tags`, `secretDueAt`, `rotationIntervalDays`, `idempotencyKey` | Update by ID or create/upsert by project and name. Human-only. |
|
|
229
|
+
|
|
230
|
+
### Record lifecycle and sharing
|
|
231
|
+
|
|
232
|
+
| Tool | Inputs | Purpose |
|
|
233
|
+
|---|---|---|
|
|
234
|
+
| `update_record_metadata` | `recordId`; at least one of `name`, `tags`, `secretDueAt`, `rotationIntervalDays` | Change safe record metadata. |
|
|
235
|
+
| `set_record_archive` | `recordId`, `archived` | Archive or restore a record. |
|
|
236
|
+
| `transfer_record_ownership` | `recordId`, `newOwnerUserId` | Transfer record ownership to an eligible user. |
|
|
237
|
+
| `list_record_versions` | `recordId` | List record version history. |
|
|
238
|
+
| `rollback_record` | `recordId`, `targetVersionId` | Restore an earlier encrypted version. |
|
|
239
|
+
| `rotate_record` | `recordId` | Rotate the record key and encrypted value locally. |
|
|
240
|
+
| `share_record_user` | `recordId`, `userId`; optional `permission` | Share a record with one user. |
|
|
241
|
+
| `share_record_service_account` | `accountId`, `recordId`, `serviceAccountId` | Share a record with one Service Account. |
|
|
242
|
+
| `share_record_group` | `recordId`, `groupId` | Share a record with a group. |
|
|
243
|
+
| `revoke_record_user` | `recordId`, `userId` | Remove one user's record access. |
|
|
244
|
+
| `revoke_record_service_account` | `recordId`, `serviceAccountId` | Remove one Service Account's record access. |
|
|
245
|
+
| `revoke_record_group` | `recordId`, `groupId` | Remove a group's record access. |
|
|
246
|
+
|
|
247
|
+
### Record audit
|
|
248
|
+
|
|
249
|
+
| Tool | Inputs | Purpose |
|
|
250
|
+
|---|---|---|
|
|
251
|
+
| `read_record_audit` | `recordId`; optional `limit` | Read audit events for one record. |
|
|
252
|
+
| `list_record_anomalies` | Optional `accountId`, `scopeType`, `scopeId` | List unusual record events. |
|
|
253
|
+
| `list_record_activity` | `day`; optional `accountId`, `scopeType`, `scopeId` | Read one UTC day's record activity. |
|
|
254
|
+
| `list_record_alerts` | Optional `accountId`, `scopeType`, `scopeId`, `limit`, `offset` | Read the record alert feed. |
|
|
255
|
+
| `list_record_access` | Optional `accountId`, `scopeType`, `scopeId`, `limit`, `offset`, `actions` | Read the record access feed. |
|
|
256
|
+
|
|
257
|
+
### Providers and gateway setup
|
|
258
|
+
|
|
259
|
+
| Tool | Inputs | Purpose |
|
|
260
|
+
|---|---|---|
|
|
261
|
+
| `list_providers` | None | List enabled AI providers. |
|
|
262
|
+
| `list_provider_credentials` | `accountId` | List safe provider credential metadata. |
|
|
263
|
+
| `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`. |
|
|
264
|
+
| `list_provider_models` | `accountId`, `credentialId` | List models available through a provider credential. |
|
|
265
|
+
| `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. |
|
|
266
|
+
| `rename_provider_credential` | `accountId`, `credentialId`, `label` | Change a provider credential label. |
|
|
267
|
+
| `revoke_provider_credential` | `accountId`, `credentialId` | Revoke a provider credential. |
|
|
268
|
+
| `list_gateways` | `projectId` | List gateways in one project. |
|
|
269
|
+
| `create_gateway` | `accountId`, `projectId`, `name`; optional `slug`, `defaultProviderId`, `defaultModel`, `credentialIds`, `credentialBindings` | Create a gateway, optionally with explicit provider defaults and credential/model bindings. |
|
|
270
|
+
| `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. |
|
|
271
|
+
| `get_connection_config` | `gatewayId` | Return provider-compatible connection URLs for a gateway. |
|
|
272
|
+
| `set_routing` | `accountId`, `gatewayId`; optional `name`, `isActive`, `attachCredentialId`, nullable `defaultProviderId`, nullable `defaultModel` | Update gateway metadata/default routing and optionally attach one credential to one live-catalog model. A non-empty `defaultModel` is required with `attachCredentialId`. |
|
|
273
|
+
| `set_gateway_settings` | `accountId`, `gatewayId`; at least one optional settings field | Update limits, logging, guardrails, caching or allowed models. |
|
|
274
|
+
| `detach_gateway_credential` | `accountId`, `gatewayId`, `credentialId` | Detach a provider credential without revoking it. |
|
|
275
|
+
| `delete_gateway` | `accountId`, `gatewayId` | Disable a gateway and revoke its tokens. |
|
|
276
|
+
|
|
277
|
+
### Gateway tokens
|
|
278
|
+
|
|
279
|
+
| Tool | Inputs | Purpose |
|
|
280
|
+
|---|---|---|
|
|
281
|
+
| `list_gateway_tokens` | `gatewayId` | List safe gateway token metadata. |
|
|
282
|
+
| `create_gateway_token` | `accountId`, `gatewayId`, `name`; optional `scopes`, `expiresInDays`, `principal`, `allowedModels`, `spendLimit`, `spendWindow`, `rateLimitPerMin` | Create a constrained gateway token and return its value once. |
|
|
283
|
+
| `rename_gateway_token` | `accountId`, `gatewayId`, `tokenId`, `name` | Change a gateway token label. |
|
|
284
|
+
| `revoke_gateway_token` | `accountId`, `gatewayId`, `tokenId` | Stop a gateway token from authenticating. |
|
|
285
|
+
| `delete_gateway_token` | `accountId`, `gatewayId`, `tokenId` | Delete gateway token metadata. |
|
|
286
|
+
|
|
287
|
+
### Logs, usage and OpenTelemetry
|
|
288
|
+
|
|
289
|
+
| Tool | Inputs | Purpose |
|
|
290
|
+
|---|---|---|
|
|
291
|
+
| `read_usage` | `gatewayId`; optional `since`, `provider`, `model`, `status`, `limit`, `offset` | Read filtered request metadata for one gateway. |
|
|
292
|
+
| `read_gateway_log` | `gatewayId`, `logId` | Read stored request and response bodies for one gateway log. |
|
|
293
|
+
| `read_gateway_key_access` | `gatewayId`; optional `outcome`, `since`, `limit`, `offset` | List provider credential access outcomes. |
|
|
294
|
+
| `list_usage_logs` | `projectId`; optional `since`, `provider`, `model`, `status`, `gatewayId`, `limit`, `offset` | List usage across a project. |
|
|
295
|
+
| `read_usage_log` | `projectId`, `logId` | Read one project's stored request and response bodies. |
|
|
296
|
+
| `read_usage_spend` | `projectId` | Compare spend with effective limits. |
|
|
297
|
+
| `read_usage_metrics` | `projectId`; optional `since`, `bucket` | Read request, error, token, latency and spend metrics. |
|
|
298
|
+
| `get_otel_export` | `accountId`, `gatewayId` | Read safe OpenTelemetry export settings. |
|
|
299
|
+
| `set_otel_export` | `accountId`, `gatewayId`; optional export fields | Update OpenTelemetry export settings. |
|
|
300
|
+
|
|
301
|
+
### Input rules
|
|
302
|
+
|
|
303
|
+
- IDs are UUID strings. Copy them from AIRCTRL instead of asking an agent to guess them.
|
|
304
|
+
- Dates and timestamps use ISO 8601. `day` uses `YYYY-MM-DD`; `since` accepts a complete timestamp.
|
|
305
|
+
- `read_record.scope` accepts sections only: `fields`, `meta`, `owner`, `access`, or `full`. It does not select individual field names.
|
|
306
|
+
- `read_record.environment` is reserved for forward compatibility and does not currently filter fields.
|
|
307
|
+
- `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.
|
|
308
|
+
- Pagination starts at `offset: 0`. Keep `limit` small when an agent only needs a summary.
|
|
309
|
+
- `accountId` selects the account. It does not grant access to it.
|
|
310
|
+
- `projectId`, `recordId`, `gatewayId`, `credentialId` and `tokenId` select resources. AIRCTRL still checks RBAC and resource access.
|
|
311
|
+
- Optional booleans must be real JSON booleans such as `true`, not strings such as `"true"`.
|
|
312
|
+
- Tools that create credentials or tokens can return a value only once. Save it immediately in an approved destination.
|
|
313
|
+
|
|
314
|
+
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.
|
|
315
|
+
|
|
316
|
+
### Complete workflow examples
|
|
317
|
+
|
|
318
|
+
#### Inspect a project without decrypting records
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
`list_records` returns safe metadata. It does not decrypt secret fields.
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
```text
|
|
327
|
+
Show the first 25 active records in project
|
|
328
|
+
"00000000-0000-4000-8000-000000000010". Return only record names,
|
|
329
|
+
formats, tags and IDs. Do not decrypt any values.
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
**MCP tool used:** `list_records`
|
|
335
|
+
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
#### Read one secret locally
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
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.
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
```text
|
|
347
|
+
Read record "00000000-0000-4000-8000-000000000020" locally. Use its value
|
|
348
|
+
only for this task. Do not print it, log it or include it in your final response.
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
**MCP tool used:** `get_secret`
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
|
|
357
|
+
#### Create a generated password record
|
|
358
|
+
|
|
359
|
+
|
|
360
|
+
|
|
361
|
+
`create_record` encrypts the generated fields locally before sending the record to AIRCTRL.
|
|
362
|
+
|
|
363
|
+
|
|
364
|
+
|
|
365
|
+
```text
|
|
366
|
+
Create a password record named "Production database password" in project
|
|
367
|
+
"00000000-0000-4000-8000-000000000010" and generate a 32-character value
|
|
368
|
+
locally. Before creating it, confirm the project ID, name and format. Never
|
|
369
|
+
print the generated password.
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
**MCP tool used:** `create_record`
|
|
375
|
+
|
|
376
|
+
|
|
377
|
+
|
|
378
|
+
#### Set up a gateway from an environment variable
|
|
379
|
+
|
|
380
|
+
|
|
381
|
+
|
|
382
|
+
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.
|
|
383
|
+
|
|
384
|
+
|
|
385
|
+
|
|
386
|
+
```text
|
|
387
|
+
Set up an OpenAI gateway named "Production gateway" in project
|
|
388
|
+
"00000000-0000-4000-8000-000000000010". Read the provider key from
|
|
389
|
+
"AIRCTRL_MCP_KEY_OPENAI_PRODUCTION", use "gpt-5" by default, and name the
|
|
390
|
+
first gateway token "Local development". Show the proposed details and wait
|
|
391
|
+
for my confirmation. Never print the environment variable value.
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
|
|
396
|
+
**MCP tool used:** `setup_gateway`
|
|
397
|
+
|
|
398
|
+
|
|
399
|
+
|
|
400
|
+
#### Review usage before changing limits
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
This separates a read-only review from the later write.
|
|
405
|
+
|
|
406
|
+
|
|
407
|
+
|
|
408
|
+
```text
|
|
409
|
+
Review current spend and request rates for project
|
|
410
|
+
"00000000-0000-4000-8000-000000000010". Propose exact new limits, but do not
|
|
411
|
+
change any gateway setting until I approve those values.
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
|
|
415
|
+
|
|
416
|
+
**MCP tools used:** `read_usage_spend`, `read_usage_metrics`, `set_gateway_settings`
|
|
417
|
+
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
#### Revoke a gateway token
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
|
|
424
|
+
Revocation takes effect immediately. Listing a token never returns its secret value.
|
|
425
|
+
|
|
426
|
+
|
|
427
|
+
|
|
428
|
+
```text
|
|
429
|
+
List tokens for gateway 00000000-0000-4000-8000-000000000030.
|
|
430
|
+
Find the token named "Old laptop". Show its ID and status, then wait for confirmation.
|
|
431
|
+
After confirmation, revoke only that token and report its final status.
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
|
|
435
|
+
|
|
436
|
+
**MCP tools used:** `list_gateway_tokens`, `revoke_gateway_token`
|
|
437
|
+
|
|
438
|
+
|
|
439
|
+
|
|
440
|
+
### Tool results
|
|
441
|
+
|
|
442
|
+
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.
|
|
443
|
+
|
|
444
|
+
Local helpers behave differently:
|
|
445
|
+
|
|
446
|
+
| Tool | Result |
|
|
447
|
+
|---|---|
|
|
448
|
+
| `airctrl_status` | Selected API URL, identity mode and configuration status; never credentials. |
|
|
449
|
+
| `list_secret_types` | Supported secret formats and their field definitions. |
|
|
450
|
+
| `generate_secret` | Generated secret fields in memory; nothing is stored until another tool creates or updates a record. |
|
|
451
|
+
|
|
452
|
+
### Tool failures
|
|
453
|
+
|
|
454
|
+
An MCP failure includes a safe AIRCTRL code and explanation. The tool does not return a successful result when the API denied the operation.
|
|
455
|
+
|
|
456
|
+
| Failure | Meaning | Next action |
|
|
457
|
+
|---|---|---|
|
|
458
|
+
| Invalid input | A required ID or field is missing or malformed. | Correct the tool arguments. |
|
|
459
|
+
| `service_account_not_supported` | The selected Service Account identity cannot use this tool. | Use a human PAT for an approved human-only operation. |
|
|
460
|
+
| `not_authorized` or `insufficient_permission` | The identity lacks the required role or resource access. | Change access in the AIRCTRL web app; do not retry unchanged. |
|
|
461
|
+
| Resource not found | The ID is wrong, unavailable or hidden from the identity. | Recheck the ID and account or project context. |
|
|
462
|
+
| `rate_limited` | Too many requests were made. | Wait and retry with a bounded backoff. |
|
|
463
|
+
|
|
464
|
+
Never ask an agent to work around an authorization failure by trying unrelated accounts, projects or IDs.
|
|
465
|
+
|
|
466
|
+
### Short agent requests
|
|
467
|
+
|
|
468
|
+
```text
|
|
469
|
+
List the projects in account 00000000-0000-4000-8000-000000000001.
|
|
470
|
+
Do not create or update anything.
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
```text
|
|
474
|
+
Create a gateway in project 00000000-0000-4000-8000-000000000010.
|
|
475
|
+
Use the OpenAI key stored in AIRCTRL_MCP_KEY_OPENAI_PRODUCTION.
|
|
476
|
+
Before executing, show me the project ID, provider, gateway name and requested token limits.
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
```text
|
|
480
|
+
Show record metadata for project 00000000-0000-4000-8000-000000000010.
|
|
481
|
+
Do not decrypt record values.
|
|
482
|
+
```
|
|
483
|
+
## MCP prompt catalog
|
|
484
|
+
|
|
485
|
+
These prompts describe what you want in everyday language. Replace the sample IDs with IDs you obtained from AIRCTRL. For write operations, the prompt asks the agent to show the final input before execution. The tool names appear below each prompt only as a technical reference.
|
|
486
|
+
|
|
487
|
+
### How to use this catalog
|
|
488
|
+
|
|
489
|
+
1. Ask AIRCTRL to check its configuration when identity mode is uncertain.
|
|
490
|
+
2. Replace every sample ID with an ID returned by AIRCTRL; do not ask the agent to invent one.
|
|
491
|
+
3. Keep discovery and mutation as separate steps.
|
|
492
|
+
4. Require a preview before a write or destructive tool.
|
|
493
|
+
5. Tell the agent whether plaintext may enter its context.
|
|
494
|
+
6. Stop on `403` instead of asking the agent to search for broader access.
|
|
495
|
+
|
|
496
|
+
Each heading lets you find the matching MCP capability. You do not need to include that heading or any tool name in your request. [MCP workflows](https://docs.airctrl.dev/mcp/workflows) combines these prompts into complete tasks with explicit review points.
|
|
497
|
+
|
|
498
|
+
### Status and projects
|
|
499
|
+
|
|
500
|
+
#### Check AIRCTRL configuration
|
|
501
|
+
|
|
502
|
+
|
|
503
|
+
|
|
504
|
+
Use this first when you are unsure which profile MCP loaded.
|
|
505
|
+
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
```text
|
|
509
|
+
Check how AIRCTRL is currently configured. Tell me which API environment and identity type are active. Do not reveal tokens, private keys or local file paths.
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
|
|
513
|
+
|
|
514
|
+
**MCP tool used:** `airctrl_status`
|
|
515
|
+
|
|
516
|
+
|
|
517
|
+
|
|
518
|
+
#### List accessible accounts
|
|
519
|
+
|
|
520
|
+
|
|
521
|
+
|
|
522
|
+
This tool requires a human PAT.
|
|
523
|
+
|
|
524
|
+
|
|
525
|
+
|
|
526
|
+
```text
|
|
527
|
+
Show me every AIRCTRL account I can access, including each name and ID. Do not change anything.
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
|
|
531
|
+
|
|
532
|
+
**MCP tool used:** `list_accounts`
|
|
533
|
+
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
#### List projects
|
|
537
|
+
|
|
538
|
+
```text
|
|
539
|
+
Show the active projects in account "00000000-0000-4000-8000-000000000001". Include each project name, ID and current state. Leave archived projects out.
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
|
|
543
|
+
|
|
544
|
+
**MCP tool used:** `list_projects`
|
|
545
|
+
|
|
546
|
+
|
|
547
|
+
|
|
548
|
+
#### View a project
|
|
549
|
+
|
|
550
|
+
```text
|
|
551
|
+
Show me project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Summarize it without changing anything.
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
|
|
555
|
+
|
|
556
|
+
**MCP tool used:** `get_project`
|
|
557
|
+
|
|
558
|
+
|
|
559
|
+
|
|
560
|
+
#### Create a project
|
|
561
|
+
|
|
562
|
+
|
|
563
|
+
|
|
564
|
+
The result includes the new project ID.
|
|
565
|
+
|
|
566
|
+
|
|
567
|
+
|
|
568
|
+
```text
|
|
569
|
+
Create a project named "Payments" in account "00000000-0000-4000-8000-000000000001" with the description "Credentials used by the payments service". Show me the exact details and wait for my confirmation before creating it.
|
|
570
|
+
```
|
|
571
|
+
|
|
572
|
+
|
|
573
|
+
|
|
574
|
+
**MCP tool used:** `create_project`
|
|
575
|
+
|
|
576
|
+
|
|
577
|
+
|
|
578
|
+
#### Update a project
|
|
579
|
+
|
|
580
|
+
```text
|
|
581
|
+
Update project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Its name should be "Payments production", its description "Production credentials", and it should remain active. Show every resulting value and wait for my confirmation.
|
|
582
|
+
```
|
|
583
|
+
|
|
584
|
+
|
|
585
|
+
|
|
586
|
+
**MCP tool used:** `update_project`
|
|
587
|
+
|
|
588
|
+
|
|
589
|
+
|
|
590
|
+
#### Archive or restore a project
|
|
591
|
+
|
|
592
|
+
|
|
593
|
+
|
|
594
|
+
Use `archived: false` to restore it.
|
|
595
|
+
|
|
596
|
+
|
|
597
|
+
|
|
598
|
+
```text
|
|
599
|
+
Archive project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Show me its name and ID, then wait for my confirmation.
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
|
|
603
|
+
|
|
604
|
+
**MCP tool used:** `set_project_archive`
|
|
605
|
+
|
|
606
|
+
|
|
607
|
+
|
|
608
|
+
### Service Account metadata
|
|
609
|
+
|
|
610
|
+
#### List Service Accounts
|
|
611
|
+
|
|
612
|
+
```text
|
|
613
|
+
Show me the Service Accounts in account "00000000-0000-4000-8000-000000000001". Return only their names, IDs, providers and states.
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
|
|
617
|
+
|
|
618
|
+
**MCP tool used:** `list_service_accounts`
|
|
619
|
+
|
|
620
|
+
|
|
621
|
+
|
|
622
|
+
#### View a Service Account
|
|
623
|
+
|
|
624
|
+
|
|
625
|
+
|
|
626
|
+
Both metadata tools require a human PAT.
|
|
627
|
+
|
|
628
|
+
|
|
629
|
+
|
|
630
|
+
```text
|
|
631
|
+
Show me Service Account "00000000-0000-4000-8000-000000000040" in account "00000000-0000-4000-8000-000000000001". Only return safe metadata; do not change its state or credentials.
|
|
632
|
+
```
|
|
633
|
+
|
|
634
|
+
|
|
635
|
+
|
|
636
|
+
**MCP tool used:** `get_service_account`
|
|
637
|
+
|
|
638
|
+
|
|
639
|
+
|
|
640
|
+
### Record reading and local generation
|
|
641
|
+
|
|
642
|
+
#### List record metadata
|
|
643
|
+
|
|
644
|
+
```text
|
|
645
|
+
Show the first 25 active records in project "00000000-0000-4000-8000-000000000010". Return only names, formats, tags and IDs. Do not decrypt any values.
|
|
646
|
+
```
|
|
647
|
+
|
|
648
|
+
|
|
649
|
+
|
|
650
|
+
**MCP tool used:** `list_records`
|
|
651
|
+
|
|
652
|
+
|
|
653
|
+
|
|
654
|
+
#### Read a complete record
|
|
655
|
+
|
|
656
|
+
```text
|
|
657
|
+
Read record "00000000-0000-4000-8000-000000000020" locally. Use its decrypted fields only for this task. Do not print, log or repeat them in your response.
|
|
658
|
+
```
|
|
659
|
+
|
|
660
|
+
|
|
661
|
+
|
|
662
|
+
**MCP tool used:** `get_secret`
|
|
663
|
+
|
|
664
|
+
|
|
665
|
+
|
|
666
|
+
#### Read the record fields section
|
|
667
|
+
|
|
668
|
+
```text
|
|
669
|
+
From record "00000000-0000-4000-8000-000000000020", read the fields section locally. This gives the local MCP client and agent the complete decrypted field map. Use the values only for the approved task, and do not print, log or repeat them.
|
|
670
|
+
```
|
|
671
|
+
|
|
672
|
+
|
|
673
|
+
|
|
674
|
+
**MCP tool used:** `read_record`
|
|
675
|
+
|
|
676
|
+
|
|
677
|
+
|
|
678
|
+
#### Load all project records
|
|
679
|
+
|
|
680
|
+
|
|
681
|
+
|
|
682
|
+
This can expose many records to the agent. Prefer `read_record` when one record is enough.
|
|
683
|
+
|
|
684
|
+
|
|
685
|
+
|
|
686
|
+
```text
|
|
687
|
+
Load every accessible record from project "00000000-0000-4000-8000-000000000010" for this task. Use decrypted values only as environment input and never include them in chat output.
|
|
688
|
+
```
|
|
689
|
+
|
|
690
|
+
|
|
691
|
+
|
|
692
|
+
**MCP tool used:** `get_all`
|
|
693
|
+
|
|
694
|
+
|
|
695
|
+
|
|
696
|
+
#### View supported record formats
|
|
697
|
+
|
|
698
|
+
|
|
699
|
+
|
|
700
|
+
This helper is local and does not call the API.
|
|
701
|
+
|
|
702
|
+
|
|
703
|
+
|
|
704
|
+
```text
|
|
705
|
+
Show me the record formats AIRCTRL supports, their required fields and which ones AIRCTRL can generate. Do not create anything.
|
|
706
|
+
```
|
|
707
|
+
|
|
708
|
+
|
|
709
|
+
|
|
710
|
+
**MCP tool used:** `list_secret_types`
|
|
711
|
+
|
|
712
|
+
|
|
713
|
+
|
|
714
|
+
#### Generate a secret locally
|
|
715
|
+
|
|
716
|
+
|
|
717
|
+
|
|
718
|
+
This helper generates values locally and stores nothing.
|
|
719
|
+
|
|
720
|
+
|
|
721
|
+
|
|
722
|
+
```text
|
|
723
|
+
Generate a 32-character password locally. Do not store or print its value. Tell me only whether generation succeeded.
|
|
724
|
+
```
|
|
725
|
+
|
|
726
|
+
|
|
727
|
+
|
|
728
|
+
**MCP tool used:** `generate_secret`
|
|
729
|
+
|
|
730
|
+
|
|
731
|
+
|
|
732
|
+
#### Create an encrypted record
|
|
733
|
+
|
|
734
|
+
```text
|
|
735
|
+
Create a password record named "Generated database password" in project "00000000-0000-4000-8000-000000000010" and generate a 32-character value locally. Show the non-secret details and wait for my confirmation. Never print the generated value.
|
|
736
|
+
```
|
|
737
|
+
|
|
738
|
+
|
|
739
|
+
|
|
740
|
+
**MCP tool used:** `create_record`
|
|
741
|
+
|
|
742
|
+
|
|
743
|
+
|
|
744
|
+
#### Replace record fields
|
|
745
|
+
|
|
746
|
+
|
|
747
|
+
|
|
748
|
+
When no `recordId` is used, supply `projectId`, `name` and `secretFormat` to create or update by name.
|
|
749
|
+
|
|
750
|
+
|
|
751
|
+
|
|
752
|
+
```text
|
|
753
|
+
Replace the "password" field in record "00000000-0000-4000-8000-000000000020" using the value from the trusted local environment. Confirm the record ID and field name, but never display the value.
|
|
754
|
+
```
|
|
755
|
+
|
|
756
|
+
|
|
757
|
+
|
|
758
|
+
**MCP tool used:** `set_secret`
|
|
759
|
+
|
|
760
|
+
|
|
761
|
+
|
|
762
|
+
### Record lifecycle
|
|
763
|
+
|
|
764
|
+
#### Update record details
|
|
765
|
+
|
|
766
|
+
```text
|
|
767
|
+
Update record "00000000-0000-4000-8000-000000000020" with the tags "payments" and "production", a due date of "2026-12-01T00:00:00Z", and a 90-day rotation interval. Show the changes and wait for my confirmation.
|
|
768
|
+
```
|
|
769
|
+
|
|
770
|
+
|
|
771
|
+
|
|
772
|
+
**MCP tool used:** `update_record_metadata`
|
|
773
|
+
|
|
774
|
+
|
|
775
|
+
|
|
776
|
+
#### Archive or restore a record
|
|
777
|
+
|
|
778
|
+
```text
|
|
779
|
+
Archive record "00000000-0000-4000-8000-000000000020". Show me its name and ID, then wait for my confirmation.
|
|
780
|
+
```
|
|
781
|
+
|
|
782
|
+
|
|
783
|
+
|
|
784
|
+
**MCP tool used:** `set_record_archive`
|
|
785
|
+
|
|
786
|
+
|
|
787
|
+
|
|
788
|
+
#### Transfer record ownership
|
|
789
|
+
|
|
790
|
+
```text
|
|
791
|
+
Transfer ownership of record "00000000-0000-4000-8000-000000000020" to user "00000000-0000-4000-8000-000000000050". Show the current and new owner, then wait for my explicit confirmation.
|
|
792
|
+
```
|
|
793
|
+
|
|
794
|
+
|
|
795
|
+
|
|
796
|
+
**MCP tool used:** `transfer_record_ownership`
|
|
797
|
+
|
|
798
|
+
|
|
799
|
+
|
|
800
|
+
#### View record version history
|
|
801
|
+
|
|
802
|
+
```text
|
|
803
|
+
Show the version history for record "00000000-0000-4000-8000-000000000020", including version IDs, creation times and which version is current. Do not change anything.
|
|
804
|
+
```
|
|
805
|
+
|
|
806
|
+
|
|
807
|
+
|
|
808
|
+
**MCP tool used:** `list_record_versions`
|
|
809
|
+
|
|
810
|
+
|
|
811
|
+
|
|
812
|
+
#### Restore a previous record version
|
|
813
|
+
|
|
814
|
+
```text
|
|
815
|
+
Restore record "00000000-0000-4000-8000-000000000020" from version "00000000-0000-4000-8000-000000000021". Explain what the rollback creates, then wait for my confirmation.
|
|
816
|
+
```
|
|
817
|
+
|
|
818
|
+
|
|
819
|
+
|
|
820
|
+
**MCP tool used:** `rollback_record`
|
|
821
|
+
|
|
822
|
+
|
|
823
|
+
|
|
824
|
+
#### Rotate a record
|
|
825
|
+
|
|
826
|
+
```text
|
|
827
|
+
Rotate record "00000000-0000-4000-8000-000000000020". Confirm its name and explain what will change, without exposing its value, then wait for my confirmation.
|
|
828
|
+
```
|
|
829
|
+
|
|
830
|
+
|
|
831
|
+
|
|
832
|
+
**MCP tool used:** `rotate_record`
|
|
833
|
+
|
|
834
|
+
|
|
835
|
+
|
|
836
|
+
### Record sharing
|
|
837
|
+
|
|
838
|
+
#### Share a record with a user
|
|
839
|
+
|
|
840
|
+
```text
|
|
841
|
+
Give user "00000000-0000-4000-8000-000000000050" read access to record "00000000-0000-4000-8000-000000000020". Verify that the user is eligible and wait for my confirmation.
|
|
842
|
+
```
|
|
843
|
+
|
|
844
|
+
|
|
845
|
+
|
|
846
|
+
**MCP tool used:** `share_record_user`
|
|
847
|
+
|
|
848
|
+
|
|
849
|
+
|
|
850
|
+
#### Share a record with a Service Account
|
|
851
|
+
|
|
852
|
+
```text
|
|
853
|
+
Give Service Account "00000000-0000-4000-8000-000000000040" access to record "00000000-0000-4000-8000-000000000020" in account "00000000-0000-4000-8000-000000000001". Show the target names and IDs, then wait for my confirmation.
|
|
854
|
+
```
|
|
855
|
+
|
|
856
|
+
|
|
857
|
+
|
|
858
|
+
**MCP tool used:** `share_record_service_account`
|
|
859
|
+
|
|
860
|
+
|
|
861
|
+
|
|
862
|
+
#### Share a record with a group
|
|
863
|
+
|
|
864
|
+
```text
|
|
865
|
+
Share record "00000000-0000-4000-8000-000000000020" with group "00000000-0000-4000-8000-000000000060". Verify that both belong to the same account and project, then wait for my confirmation.
|
|
866
|
+
```
|
|
867
|
+
|
|
868
|
+
|
|
869
|
+
|
|
870
|
+
**MCP tool used:** `share_record_group`
|
|
871
|
+
|
|
872
|
+
|
|
873
|
+
|
|
874
|
+
#### Remove a user's record access
|
|
875
|
+
|
|
876
|
+
```text
|
|
877
|
+
Remove user "00000000-0000-4000-8000-000000000050" from record "00000000-0000-4000-8000-000000000020". Explain that access ends immediately, then wait for my confirmation.
|
|
878
|
+
```
|
|
879
|
+
|
|
880
|
+
|
|
881
|
+
|
|
882
|
+
**MCP tool used:** `revoke_record_user`
|
|
883
|
+
|
|
884
|
+
|
|
885
|
+
|
|
886
|
+
#### Remove a Service Account's record access
|
|
887
|
+
|
|
888
|
+
```text
|
|
889
|
+
Remove Service Account "00000000-0000-4000-8000-000000000040" from record "00000000-0000-4000-8000-000000000020". Confirm that grants for other Service Accounts will remain unchanged, then wait for my approval.
|
|
890
|
+
```
|
|
891
|
+
|
|
892
|
+
|
|
893
|
+
|
|
894
|
+
**MCP tool used:** `revoke_record_service_account`
|
|
895
|
+
|
|
896
|
+
|
|
897
|
+
|
|
898
|
+
#### Remove a group's record access
|
|
899
|
+
|
|
900
|
+
```text
|
|
901
|
+
Remove group "00000000-0000-4000-8000-000000000060" from record "00000000-0000-4000-8000-000000000020". Show the target names and IDs, then wait for my confirmation.
|
|
902
|
+
```
|
|
903
|
+
|
|
904
|
+
|
|
905
|
+
|
|
906
|
+
**MCP tool used:** `revoke_record_group`
|
|
907
|
+
|
|
908
|
+
|
|
909
|
+
|
|
910
|
+
### Record audit
|
|
911
|
+
|
|
912
|
+
#### Review one record's audit history
|
|
913
|
+
|
|
914
|
+
```text
|
|
915
|
+
Show the 25 most recent audit events for record "00000000-0000-4000-8000-000000000020". Summarize actions, actors and timestamps without exposing secret fields.
|
|
916
|
+
```
|
|
917
|
+
|
|
918
|
+
|
|
919
|
+
|
|
920
|
+
**MCP tool used:** `read_record_audit`
|
|
921
|
+
|
|
922
|
+
|
|
923
|
+
|
|
924
|
+
#### Find unusual record activity
|
|
925
|
+
|
|
926
|
+
```text
|
|
927
|
+
Show unusual record activity in project "00000000-0000-4000-8000-000000000010" under account "00000000-0000-4000-8000-000000000001". Group the results by severity.
|
|
928
|
+
```
|
|
929
|
+
|
|
930
|
+
|
|
931
|
+
|
|
932
|
+
**MCP tool used:** `list_record_anomalies`
|
|
933
|
+
|
|
934
|
+
|
|
935
|
+
|
|
936
|
+
#### Review daily record activity
|
|
937
|
+
|
|
938
|
+
```text
|
|
939
|
+
Summarize record activity for project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001" on the UTC day "2026-09-10".
|
|
940
|
+
```
|
|
941
|
+
|
|
942
|
+
|
|
943
|
+
|
|
944
|
+
**MCP tool used:** `list_record_activity`
|
|
945
|
+
|
|
946
|
+
|
|
947
|
+
|
|
948
|
+
#### Review record alerts
|
|
949
|
+
|
|
950
|
+
```text
|
|
951
|
+
Show the first 25 record alerts for project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Do not take corrective action.
|
|
952
|
+
```
|
|
953
|
+
|
|
954
|
+
|
|
955
|
+
|
|
956
|
+
**MCP tool used:** `list_record_alerts`
|
|
957
|
+
|
|
958
|
+
|
|
959
|
+
|
|
960
|
+
#### Review secret access events
|
|
961
|
+
|
|
962
|
+
```text
|
|
963
|
+
Show the first 25 secret-access events for records in project "00000000-0000-4000-8000-000000000010" under account "00000000-0000-4000-8000-000000000001".
|
|
964
|
+
```
|
|
965
|
+
|
|
966
|
+
|
|
967
|
+
|
|
968
|
+
**MCP tool used:** `list_record_access`
|
|
969
|
+
|
|
970
|
+
|
|
971
|
+
|
|
972
|
+
### Providers and credentials
|
|
973
|
+
|
|
974
|
+
#### List supported AI providers
|
|
975
|
+
|
|
976
|
+
```text
|
|
977
|
+
Show the AI providers AIRCTRL supports, including their names, IDs and available configuration. Do not add any credentials.
|
|
978
|
+
```
|
|
979
|
+
|
|
980
|
+
|
|
981
|
+
|
|
982
|
+
**MCP tool used:** `list_providers`
|
|
983
|
+
|
|
984
|
+
|
|
985
|
+
|
|
986
|
+
#### List provider credentials
|
|
987
|
+
|
|
988
|
+
```text
|
|
989
|
+
Show the provider credentials in account "00000000-0000-4000-8000-000000000001". Return labels, IDs, providers and validation status, but never request secret values.
|
|
990
|
+
```
|
|
991
|
+
|
|
992
|
+
|
|
993
|
+
|
|
994
|
+
**MCP tool used:** `list_provider_credentials`
|
|
995
|
+
|
|
996
|
+
|
|
997
|
+
|
|
998
|
+
#### Add a provider credential
|
|
999
|
+
|
|
1000
|
+
```text
|
|
1001
|
+
Add a provider credential named "Production OpenAI" to account "00000000-0000-4000-8000-000000000001" for provider "00000000-0000-4000-8000-000000000070". Read the key from environment variable "AIRCTRL_MCP_KEY_OPENAI_PRODUCTION". Confirm only the variable name, never its value, then wait for my approval.
|
|
1002
|
+
```
|
|
1003
|
+
|
|
1004
|
+
|
|
1005
|
+
|
|
1006
|
+
**MCP tool used:** `add_provider_key`
|
|
1007
|
+
|
|
1008
|
+
|
|
1009
|
+
|
|
1010
|
+
#### List models for a credential
|
|
1011
|
+
|
|
1012
|
+
```text
|
|
1013
|
+
Show the model IDs available through provider credential "00000000-0000-4000-8000-000000000071" in account "00000000-0000-4000-8000-000000000001".
|
|
1014
|
+
```
|
|
1015
|
+
|
|
1016
|
+
|
|
1017
|
+
|
|
1018
|
+
**MCP tool used:** `list_provider_models`
|
|
1019
|
+
|
|
1020
|
+
|
|
1021
|
+
|
|
1022
|
+
#### Replace a provider key
|
|
1023
|
+
|
|
1024
|
+
```text
|
|
1025
|
+
Replace provider credential "00000000-0000-4000-8000-000000000071" in account "00000000-0000-4000-8000-000000000001" using the replacement stored in `AIRCTRL_MCP_KEY_OPENAI_ROTATION`. Never request or echo the key. Wait for my confirmation before changing it.
|
|
1026
|
+
```
|
|
1027
|
+
|
|
1028
|
+
|
|
1029
|
+
|
|
1030
|
+
**MCP tool used:** `rotate_provider_key`
|
|
1031
|
+
|
|
1032
|
+
|
|
1033
|
+
|
|
1034
|
+
#### Rename a provider credential
|
|
1035
|
+
|
|
1036
|
+
```text
|
|
1037
|
+
Rename provider credential "00000000-0000-4000-8000-000000000071" in account "00000000-0000-4000-8000-000000000001" to "Primary OpenAI". Show the current and new labels, then wait for my confirmation.
|
|
1038
|
+
```
|
|
1039
|
+
|
|
1040
|
+
|
|
1041
|
+
|
|
1042
|
+
**MCP tool used:** `rename_provider_credential`
|
|
1043
|
+
|
|
1044
|
+
|
|
1045
|
+
|
|
1046
|
+
#### Revoke a provider credential
|
|
1047
|
+
|
|
1048
|
+
```text
|
|
1049
|
+
Revoke provider credential "00000000-0000-4000-8000-000000000071" in account "00000000-0000-4000-8000-000000000001". First show every gateway that depends on it, then wait for my explicit confirmation.
|
|
1050
|
+
```
|
|
1051
|
+
|
|
1052
|
+
|
|
1053
|
+
|
|
1054
|
+
**MCP tool used:** `revoke_provider_credential`
|
|
1055
|
+
|
|
1056
|
+
|
|
1057
|
+
|
|
1058
|
+
### Gateway setup and routing
|
|
1059
|
+
|
|
1060
|
+
#### List gateways
|
|
1061
|
+
|
|
1062
|
+
```text
|
|
1063
|
+
Show the gateways in project "00000000-0000-4000-8000-000000000010", including each name, ID, provider and active state.
|
|
1064
|
+
```
|
|
1065
|
+
|
|
1066
|
+
|
|
1067
|
+
|
|
1068
|
+
**MCP tool used:** `list_gateways`
|
|
1069
|
+
|
|
1070
|
+
|
|
1071
|
+
|
|
1072
|
+
#### Create a gateway
|
|
1073
|
+
|
|
1074
|
+
```text
|
|
1075
|
+
Create a bare gateway named "Payments AI" in project "00000000-0000-4000-8000-000000000010" under account "00000000-0000-4000-8000-000000000001". Do not attach a provider key yet. Show the details and wait for my confirmation.
|
|
1076
|
+
```
|
|
1077
|
+
|
|
1078
|
+
|
|
1079
|
+
|
|
1080
|
+
**MCP tool used:** `create_gateway`
|
|
1081
|
+
|
|
1082
|
+
|
|
1083
|
+
|
|
1084
|
+
#### Set up a complete gateway
|
|
1085
|
+
|
|
1086
|
+
|
|
1087
|
+
|
|
1088
|
+
This workflow can add a provider credential, create a gateway and create a one-time gateway token.
|
|
1089
|
+
|
|
1090
|
+
|
|
1091
|
+
|
|
1092
|
+
```text
|
|
1093
|
+
Set up an OpenAI gateway named "Payments AI" 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". Explain every resource that will be created and wait for my confirmation.
|
|
1094
|
+
```
|
|
1095
|
+
|
|
1096
|
+
|
|
1097
|
+
|
|
1098
|
+
**MCP tool used:** `setup_gateway`
|
|
1099
|
+
|
|
1100
|
+
|
|
1101
|
+
|
|
1102
|
+
#### View gateway connection settings
|
|
1103
|
+
|
|
1104
|
+
```text
|
|
1105
|
+
Show me how to connect to gateway "00000000-0000-4000-8000-000000000030", including compatible base URLs and required header names. Do not create a new token.
|
|
1106
|
+
```
|
|
1107
|
+
|
|
1108
|
+
|
|
1109
|
+
|
|
1110
|
+
**MCP tool used:** `get_connection_config`
|
|
1111
|
+
|
|
1112
|
+
|
|
1113
|
+
|
|
1114
|
+
#### Change gateway routing
|
|
1115
|
+
|
|
1116
|
+
```text
|
|
1117
|
+
Attach provider credential "00000000-0000-4000-8000-000000000200" to model "gpt-5" on gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001", and make provider "00000000-0000-4000-8000-000000000070" with that model the default route. Show the current and proposed routing, then wait for my confirmation.
|
|
1118
|
+
```
|
|
1119
|
+
|
|
1120
|
+
|
|
1121
|
+
|
|
1122
|
+
**MCP tool used:** `set_routing`
|
|
1123
|
+
|
|
1124
|
+
|
|
1125
|
+
|
|
1126
|
+
#### Change gateway limits and behavior
|
|
1127
|
+
|
|
1128
|
+
```text
|
|
1129
|
+
For gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001", set a monthly spend limit of 100, a rate limit of 120 requests per minute, metadata logging without bodies, guardrails in flag mode, and a five-minute cache. Show every proposed change and wait for my confirmation.
|
|
1130
|
+
```
|
|
1131
|
+
|
|
1132
|
+
|
|
1133
|
+
|
|
1134
|
+
**MCP tool used:** `set_gateway_settings`
|
|
1135
|
+
|
|
1136
|
+
|
|
1137
|
+
|
|
1138
|
+
#### Detach a provider credential
|
|
1139
|
+
|
|
1140
|
+
```text
|
|
1141
|
+
Detach provider credential "00000000-0000-4000-8000-000000000071" from gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Confirm that another route will remain usable, then wait for my approval.
|
|
1142
|
+
```
|
|
1143
|
+
|
|
1144
|
+
|
|
1145
|
+
|
|
1146
|
+
**MCP tool used:** `detach_gateway_credential`
|
|
1147
|
+
|
|
1148
|
+
|
|
1149
|
+
|
|
1150
|
+
#### Delete a gateway
|
|
1151
|
+
|
|
1152
|
+
```text
|
|
1153
|
+
Delete gateway "00000000-0000-4000-8000-000000000030" from account "00000000-0000-4000-8000-000000000001". Explain which gateway tokens will stop working, then wait for my explicit confirmation.
|
|
1154
|
+
```
|
|
1155
|
+
|
|
1156
|
+
|
|
1157
|
+
|
|
1158
|
+
**MCP tool used:** `delete_gateway`
|
|
1159
|
+
|
|
1160
|
+
|
|
1161
|
+
|
|
1162
|
+
### Gateway tokens
|
|
1163
|
+
|
|
1164
|
+
#### List gateway tokens
|
|
1165
|
+
|
|
1166
|
+
```text
|
|
1167
|
+
Show the tokens for gateway "00000000-0000-4000-8000-000000000030", including IDs, labels, status and expiration. Never request their secret values.
|
|
1168
|
+
```
|
|
1169
|
+
|
|
1170
|
+
|
|
1171
|
+
|
|
1172
|
+
**MCP tool used:** `list_gateway_tokens`
|
|
1173
|
+
|
|
1174
|
+
|
|
1175
|
+
|
|
1176
|
+
#### Create a gateway token
|
|
1177
|
+
|
|
1178
|
+
```text
|
|
1179
|
+
Create a token named "Local development" for gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". It should expire in 30 days. Wait for my confirmation and send the one-time value only to the approved storage step.
|
|
1180
|
+
```
|
|
1181
|
+
|
|
1182
|
+
|
|
1183
|
+
|
|
1184
|
+
**MCP tool used:** `create_gateway_token`
|
|
1185
|
+
|
|
1186
|
+
|
|
1187
|
+
|
|
1188
|
+
#### Rename a gateway token
|
|
1189
|
+
|
|
1190
|
+
```text
|
|
1191
|
+
Rename token "00000000-0000-4000-8000-000000000031" on gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001" to "CI production". Show the current and new names, then wait for my confirmation.
|
|
1192
|
+
```
|
|
1193
|
+
|
|
1194
|
+
|
|
1195
|
+
|
|
1196
|
+
**MCP tool used:** `rename_gateway_token`
|
|
1197
|
+
|
|
1198
|
+
|
|
1199
|
+
|
|
1200
|
+
#### Revoke a gateway token
|
|
1201
|
+
|
|
1202
|
+
```text
|
|
1203
|
+
Revoke token "00000000-0000-4000-8000-000000000031" on gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Explain that authentication will stop immediately, then wait for my confirmation.
|
|
1204
|
+
```
|
|
1205
|
+
|
|
1206
|
+
|
|
1207
|
+
|
|
1208
|
+
**MCP tool used:** `revoke_gateway_token`
|
|
1209
|
+
|
|
1210
|
+
|
|
1211
|
+
|
|
1212
|
+
#### Delete a gateway token
|
|
1213
|
+
|
|
1214
|
+
```text
|
|
1215
|
+
Permanently delete token "00000000-0000-4000-8000-000000000031" from gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Confirm that it is already revoked, then wait for my approval.
|
|
1216
|
+
```
|
|
1217
|
+
|
|
1218
|
+
|
|
1219
|
+
|
|
1220
|
+
**MCP tool used:** `delete_gateway_token`
|
|
1221
|
+
|
|
1222
|
+
|
|
1223
|
+
|
|
1224
|
+
### Logs, usage and OpenTelemetry
|
|
1225
|
+
|
|
1226
|
+
#### Review gateway requests
|
|
1227
|
+
|
|
1228
|
+
```text
|
|
1229
|
+
Summarize up to 50 requests handled by gateway "00000000-0000-4000-8000-000000000030" since "2026-09-01T00:00:00Z". Do not read request or response bodies.
|
|
1230
|
+
```
|
|
1231
|
+
|
|
1232
|
+
|
|
1233
|
+
|
|
1234
|
+
**MCP tool used:** `read_usage`
|
|
1235
|
+
|
|
1236
|
+
|
|
1237
|
+
|
|
1238
|
+
#### Inspect one gateway request
|
|
1239
|
+
|
|
1240
|
+
```text
|
|
1241
|
+
Inspect log "00000000-0000-4000-8000-000000000080" from gateway "00000000-0000-4000-8000-000000000030". Read stored bodies only to diagnose this request and do not repeat sensitive content.
|
|
1242
|
+
```
|
|
1243
|
+
|
|
1244
|
+
|
|
1245
|
+
|
|
1246
|
+
**MCP tool used:** `read_gateway_log`
|
|
1247
|
+
|
|
1248
|
+
|
|
1249
|
+
|
|
1250
|
+
#### Review provider-key access
|
|
1251
|
+
|
|
1252
|
+
```text
|
|
1253
|
+
Show up to 50 denied provider-key access events for gateway "00000000-0000-4000-8000-000000000030" since "2026-09-01T00:00:00Z". Group the denials by reason.
|
|
1254
|
+
```
|
|
1255
|
+
|
|
1256
|
+
|
|
1257
|
+
|
|
1258
|
+
**MCP tool used:** `read_gateway_key_access`
|
|
1259
|
+
|
|
1260
|
+
|
|
1261
|
+
|
|
1262
|
+
#### Review project usage logs
|
|
1263
|
+
|
|
1264
|
+
```text
|
|
1265
|
+
Show up to 50 usage logs for gateway "00000000-0000-4000-8000-000000000030" in project "00000000-0000-4000-8000-000000000010" since "2026-09-01T00:00:00Z". Return metadata only.
|
|
1266
|
+
```
|
|
1267
|
+
|
|
1268
|
+
|
|
1269
|
+
|
|
1270
|
+
**MCP tool used:** `list_usage_logs`
|
|
1271
|
+
|
|
1272
|
+
|
|
1273
|
+
|
|
1274
|
+
#### Inspect one project usage log
|
|
1275
|
+
|
|
1276
|
+
```text
|
|
1277
|
+
Inspect usage log "00000000-0000-4000-8000-000000000080" in project "00000000-0000-4000-8000-000000000010". Do not quote request or response bodies in the final answer.
|
|
1278
|
+
```
|
|
1279
|
+
|
|
1280
|
+
|
|
1281
|
+
|
|
1282
|
+
**MCP tool used:** `read_usage_log`
|
|
1283
|
+
|
|
1284
|
+
|
|
1285
|
+
|
|
1286
|
+
#### Review project spend
|
|
1287
|
+
|
|
1288
|
+
```text
|
|
1289
|
+
Compare current spend in project "00000000-0000-4000-8000-000000000010" with its effective limit. Do not change any settings.
|
|
1290
|
+
```
|
|
1291
|
+
|
|
1292
|
+
|
|
1293
|
+
|
|
1294
|
+
**MCP tool used:** `read_usage_spend`
|
|
1295
|
+
|
|
1296
|
+
|
|
1297
|
+
|
|
1298
|
+
#### Review project usage metrics
|
|
1299
|
+
|
|
1300
|
+
```text
|
|
1301
|
+
Summarize daily requests, errors, tokens, latency and spend for project "00000000-0000-4000-8000-000000000010" since "2026-09-01T00:00:00Z".
|
|
1302
|
+
```
|
|
1303
|
+
|
|
1304
|
+
|
|
1305
|
+
|
|
1306
|
+
**MCP tool used:** `read_usage_metrics`
|
|
1307
|
+
|
|
1308
|
+
|
|
1309
|
+
|
|
1310
|
+
#### View OpenTelemetry settings
|
|
1311
|
+
|
|
1312
|
+
```text
|
|
1313
|
+
Show the OpenTelemetry export settings for gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Return only safe settings and never request stored header values.
|
|
1314
|
+
```
|
|
1315
|
+
|
|
1316
|
+
|
|
1317
|
+
|
|
1318
|
+
**MCP tool used:** `get_otel_export`
|
|
1319
|
+
|
|
1320
|
+
|
|
1321
|
+
|
|
1322
|
+
#### Change OpenTelemetry settings
|
|
1323
|
+
|
|
1324
|
+
```text
|
|
1325
|
+
Enable OpenTelemetry metrics and traces for gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Send them to "https://otel.example.com/v1/traces" and read headers from "OTEL_EXPORT_HEADERS". Show the destination and enabled data, then wait for my confirmation.
|
|
1326
|
+
```
|
|
1327
|
+
|
|
1328
|
+
|
|
1329
|
+
|
|
1330
|
+
**MCP tool used:** `set_otel_export`
|
|
1331
|
+
|
|
1332
|
+
|
|
1333
|
+
|
|
1334
|
+
### When a prompt fails
|
|
1335
|
+
|
|
1336
|
+
If a tool returns validation, permission or not-found errors, stop and explain the exact code. Do not try neighboring IDs or broader scopes. Retry only temporary `rate_limited`, `internal_error` or `service_unavailable` failures, with a short bounded backoff.
|
|
1337
|
+
## MCP workflow prompts
|
|
1338
|
+
|
|
1339
|
+
These prompts combine tools without giving the agent unlimited freedom. Each one separates discovery, review and mutation. Replace the sample IDs before use.
|
|
1340
|
+
|
|
1341
|
+
### Inspect a project without decrypting secrets
|
|
1342
|
+
|
|
1343
|
+
|
|
1344
|
+
|
|
1345
|
+
Use this for inventory and planning. It keeps plaintext outside the agent context.
|
|
1346
|
+
|
|
1347
|
+
|
|
1348
|
+
|
|
1349
|
+
```text
|
|
1350
|
+
Review project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Summarize its status and the first 50 active records, including names, formats, tags and due dates. Do not decrypt any values or change anything.
|
|
1351
|
+
```
|
|
1352
|
+
|
|
1353
|
+
|
|
1354
|
+
|
|
1355
|
+
**MCP tools used:** `get_project`, `list_records`
|
|
1356
|
+
|
|
1357
|
+
|
|
1358
|
+
|
|
1359
|
+
### Read the smallest useful record scope
|
|
1360
|
+
|
|
1361
|
+
|
|
1362
|
+
|
|
1363
|
+
Prefer this over `get_all` when one record is enough. Requesting `fields` still gives the local MCP client and agent that record's complete decrypted field map.
|
|
1364
|
+
|
|
1365
|
+
|
|
1366
|
+
|
|
1367
|
+
```text
|
|
1368
|
+
Find the record named "Payments environment" in project "00000000-0000-4000-8000-000000000010" and show only its safe metadata and ID. Wait for my confirmation. Then read its fields section locally. This gives the local MCP client and agent the complete decrypted field map. Use it only for the active task, and never print or summarize the values.
|
|
1369
|
+
```
|
|
1370
|
+
|
|
1371
|
+
|
|
1372
|
+
|
|
1373
|
+
**MCP tools used:** `list_records`, `read_record`
|
|
1374
|
+
|
|
1375
|
+
|
|
1376
|
+
|
|
1377
|
+
### Create and verify a generated record
|
|
1378
|
+
|
|
1379
|
+
```text
|
|
1380
|
+
Verify that AIRCTRL can generate passwords, then prepare a 32-character password record named "Payments database password" in project "00000000-0000-4000-8000-000000000010". Show only the non-secret details and wait for my confirmation. After creating it, confirm its name, format and ID without printing the generated value. Do not decrypt it unless I approve that separately.
|
|
1381
|
+
```
|
|
1382
|
+
|
|
1383
|
+
|
|
1384
|
+
|
|
1385
|
+
**MCP tools used:** `list_secret_types`, `create_record`, `list_records`
|
|
1386
|
+
|
|
1387
|
+
|
|
1388
|
+
|
|
1389
|
+
### Share a record with a Service Account
|
|
1390
|
+
|
|
1391
|
+
|
|
1392
|
+
|
|
1393
|
+
Sharing creates record access; it does not broaden the Service Account's RBAC permissions.
|
|
1394
|
+
|
|
1395
|
+
|
|
1396
|
+
|
|
1397
|
+
```text
|
|
1398
|
+
Give Service Account "00000000-0000-4000-8000-000000000040" access to record "00000000-0000-4000-8000-000000000020" in project "00000000-0000-4000-8000-000000000010" under account "00000000-0000-4000-8000-000000000001". First confirm that the Service Account is active and the record exists. Show both names and IDs and wait for my confirmation. Change only this record grant; do not alter roles, project assignments or credentials.
|
|
1399
|
+
```
|
|
1400
|
+
|
|
1401
|
+
|
|
1402
|
+
|
|
1403
|
+
**MCP tools used:** `get_service_account`, `list_records`, `share_record_service_account`
|
|
1404
|
+
|
|
1405
|
+
|
|
1406
|
+
|
|
1407
|
+
### Remove one Service Account grant
|
|
1408
|
+
|
|
1409
|
+
```text
|
|
1410
|
+
Remove Service Account "00000000-0000-4000-8000-000000000040" from record "00000000-0000-4000-8000-000000000020". First confirm both resources and explain that only this record grant will be removed. Wait for my explicit confirmation. Do not pause, revoke or otherwise modify the Service Account.
|
|
1411
|
+
```
|
|
1412
|
+
|
|
1413
|
+
|
|
1414
|
+
|
|
1415
|
+
**MCP tools used:** `get_service_account`, `list_records`, `revoke_record_service_account`
|
|
1416
|
+
|
|
1417
|
+
|
|
1418
|
+
|
|
1419
|
+
### Create a gateway from an environment-backed provider key
|
|
1420
|
+
|
|
1421
|
+
```text
|
|
1422
|
+
Set up an OpenAI gateway named "Payments AI" in project "00000000-0000-4000-8000-000000000010". Use the key stored in "AIRCTRL_MCP_KEY_OPENAI_PRODUCTION", model "gpt-5", and name the first gateway token "Local development". Confirm that OpenAI is enabled, explain every resource that may be created, show only the environment variable name, and wait for my approval. Send the one-time token only to the approved storage step, then return the new gateway's compatible base URLs.
|
|
1423
|
+
```
|
|
1424
|
+
|
|
1425
|
+
|
|
1426
|
+
|
|
1427
|
+
**MCP tools used:** `list_providers`, `setup_gateway`, `get_connection_config`
|
|
1428
|
+
|
|
1429
|
+
|
|
1430
|
+
|
|
1431
|
+
### Replace a gateway token safely
|
|
1432
|
+
|
|
1433
|
+
|
|
1434
|
+
|
|
1435
|
+
Never revoke the old token before the replacement has been stored and deployed.
|
|
1436
|
+
|
|
1437
|
+
|
|
1438
|
+
|
|
1439
|
+
```text
|
|
1440
|
+
Replace the active token named "CI production" on gateway "00000000-0000-4000-8000-000000000030" with a token named "CI production replacement" that expires in 30 days. Show the old token's ID and expiration, then wait for my confirmation. Send the new one-time value only to the approved storage step and stop until I confirm the workload uses it. Only then revoke the old token and report both final states.
|
|
1441
|
+
```
|
|
1442
|
+
|
|
1443
|
+
|
|
1444
|
+
|
|
1445
|
+
**MCP tools used:** `list_gateway_tokens`, `create_gateway_token`, `revoke_gateway_token`
|
|
1446
|
+
|
|
1447
|
+
|
|
1448
|
+
|
|
1449
|
+
### Diagnose gateway failures without changing configuration
|
|
1450
|
+
|
|
1451
|
+
```text
|
|
1452
|
+
Diagnose gateway "00000000-0000-4000-8000-000000000030" in project "00000000-0000-4000-8000-000000000010" since "2026-09-01T00:00:00Z". Review daily metrics, up to 25 requests with status 500, and up to 25 denied provider-key access events. Summarize timing, provider, model, status and denial reasons. Do not read bodies or change routing, credentials, limits or tokens.
|
|
1453
|
+
```
|
|
1454
|
+
|
|
1455
|
+
|
|
1456
|
+
|
|
1457
|
+
**MCP tools used:** `read_usage_metrics`, `list_usage_logs`, `read_gateway_key_access`
|
|
1458
|
+
|
|
1459
|
+
|
|
1460
|
+
|
|
1461
|
+
### Inspect one failed request deeply
|
|
1462
|
+
|
|
1463
|
+
```text
|
|
1464
|
+
Find log "00000000-0000-4000-8000-000000000080" among the 25 most recent requests for gateway "00000000-0000-4000-8000-000000000030". Show its safe metadata and ask before reading stored bodies. After I approve, diagnose the failure without quoting credentials, authorization headers or sensitive body fields.
|
|
1465
|
+
```
|
|
1466
|
+
|
|
1467
|
+
|
|
1468
|
+
|
|
1469
|
+
**MCP tools used:** `read_usage`, `read_gateway_log`
|
|
1470
|
+
|
|
1471
|
+
|
|
1472
|
+
|
|
1473
|
+
### Review spend before changing limits
|
|
1474
|
+
|
|
1475
|
+
```text
|
|
1476
|
+
Review current spend, the effective limit, request rate and error rate for project "00000000-0000-4000-8000-000000000010". Propose a specific spend limit, time window and per-minute request limit for gateway "00000000-0000-4000-8000-000000000030", but do not change anything yet. After my explicit approval, apply only the approved values and confirm the resulting effective limit.
|
|
1477
|
+
```
|
|
1478
|
+
|
|
1479
|
+
|
|
1480
|
+
|
|
1481
|
+
**MCP tools used:** `read_usage_spend`, `read_usage_metrics`, `set_gateway_settings`
|
|
1482
|
+
|
|
1483
|
+
|
|
1484
|
+
|
|
1485
|
+
### Rotate a provider key with dependency checks
|
|
1486
|
+
|
|
1487
|
+
```text
|
|
1488
|
+
Replace provider credential "00000000-0000-4000-8000-000000000071" in account "00000000-0000-4000-8000-000000000001". First show its label and provider and verify that it currently returns models. Never request or display the current secret. Use the replacement stored in `AIRCTRL_MCP_KEY_OPENAI_ROTATION`, wait for my confirmation, never echo the new value, and verify afterward that models remain available.
|
|
1489
|
+
```
|
|
1490
|
+
|
|
1491
|
+
|
|
1492
|
+
|
|
1493
|
+
**MCP tools used:** `list_provider_credentials`, `list_provider_models`, `rotate_provider_key`
|
|
1494
|
+
|
|
1495
|
+
|
|
1496
|
+
|
|
1497
|
+
### Configure OpenTelemetry and verify safe state
|
|
1498
|
+
|
|
1499
|
+
```text
|
|
1500
|
+
For gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001", show the current OpenTelemetry state, endpoint and export flags without requesting header values. Prepare to enable metrics and traces to "https://otel.example.com/v1/traces" using headers from "OTEL_EXPORT_HEADERS". Wait for my confirmation, apply the change, and report only the final safe settings.
|
|
1501
|
+
```
|
|
1502
|
+
|
|
1503
|
+
|
|
1504
|
+
|
|
1505
|
+
**MCP tools used:** `get_otel_export`, `set_otel_export`
|
|
1506
|
+
|
|
1507
|
+
|
|
1508
|
+
|
|
1509
|
+
### Decommission a gateway
|
|
1510
|
+
|
|
1511
|
+
```text
|
|
1512
|
+
Decommission gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". First review its connection settings, active tokens and 25 most recent requests. List every token that will stop working and wait for my explicit confirmation. Delete only the gateway; do not revoke provider credentials because other gateways may use them.
|
|
1513
|
+
```
|
|
1514
|
+
|
|
1515
|
+
|
|
1516
|
+
|
|
1517
|
+
**MCP tools used:** `get_connection_config`, `list_gateway_tokens`, `read_usage`, `delete_gateway`
|
|
1518
|
+
|
|
1519
|
+
|
|
1520
|
+
|
|
1521
|
+
### Stop conditions
|
|
1522
|
+
|
|
1523
|
+
Stop the workflow instead of improvising when an ID is ambiguous or a resource belongs to another account. Also stop when a Service Account is inactive, a provider key is unavailable, or the API returns an authorization error. Ask for the missing decision rather than trying broader access.
|
|
1524
|
+
## Connect Claude Code
|
|
1525
|
+
|
|
1526
|
+
Claude Code starts AIRCTRL as a local MCP process. Read [MCP setup](https://docs.airctrl.dev/mcp/setup) first to choose the right identity and keep its sensitive configuration outside your project.
|
|
1527
|
+
|
|
1528
|
+
### Add AIRCTRL to one project
|
|
1529
|
+
|
|
1530
|
+
Create `.mcp.json` in the project root and add the local server command:
|
|
1531
|
+
|
|
1532
|
+
```json
|
|
1533
|
+
{
|
|
1534
|
+
"mcpServers": {
|
|
1535
|
+
"airctrl": {
|
|
1536
|
+
"command": "npx",
|
|
1537
|
+
"args": ["-y", "@airctrl/mcp"]
|
|
1538
|
+
}
|
|
1539
|
+
}
|
|
1540
|
+
}
|
|
1541
|
+
```
|
|
1542
|
+
|
|
1543
|
+
On Windows, Claude Code requires `cmd /c npx` for an `npx` server. Set `command` to `cmd` and use `['/c', 'npx', '-y', '@airctrl/mcp']` as its arguments.
|
|
1544
|
+
|
|
1545
|
+
Add the selected human or Service Account identity through your local secure configuration, following [MCP setup](https://docs.airctrl.dev/mcp/setup). Do not mix the two identity modes.
|
|
1546
|
+
|
|
1547
|
+
### Verify the connection
|
|
1548
|
+
|
|
1549
|
+
Run this command from the project after saving the configuration:
|
|
1550
|
+
|
|
1551
|
+
```bash
|
|
1552
|
+
claude mcp get airctrl
|
|
1553
|
+
```
|
|
1554
|
+
|
|
1555
|
+
Then ask Claude Code:
|
|
1556
|
+
|
|
1557
|
+
```text
|
|
1558
|
+
Check the AIRCTRL connection. Tell me which API URL and identity type are configured. Do not read or reveal any record values.
|
|
1559
|
+
```
|
|
1560
|
+
|
|
1561
|
+
Claude Code should show the AIRCTRL MCP server and call the safe status tool. If you use a Service Account, ask it to list metadata from one assigned project instead of asking for accounts.
|
|
1562
|
+
|
|
1563
|
+
### Use it safely
|
|
1564
|
+
|
|
1565
|
+
State the account, project, and resource you intend to use. Ask for a read before any write. Review the proposed operation before approving it. Never include a token, passphrase, provider key, or decrypted value in chat.
|
|
1566
|
+
|
|
1567
|
+
### Troubleshoot or remove it
|
|
1568
|
+
|
|
1569
|
+
Use `claude mcp list` to confirm the configured name. If the server does not start, verify Node.js is available and review the local secure configuration. A `403` response means the selected identity lacks permission; changing an ID cannot grant it.
|
|
1570
|
+
|
|
1571
|
+
Remove the server with `claude mcp remove airctrl`, or delete its `airctrl` entry from `.mcp.json`. See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for client-specific options.
|
|
1572
|
+
## Connect Codex
|
|
1573
|
+
|
|
1574
|
+
Codex starts AIRCTRL as a local MCP process. The Codex desktop app, CLI, and IDE extension share the same MCP configuration. Read [MCP setup](https://docs.airctrl.dev/mcp/setup) first to choose the right identity and keep its sensitive configuration outside your project.
|
|
1575
|
+
|
|
1576
|
+
### Add AIRCTRL to one project
|
|
1577
|
+
|
|
1578
|
+
For a project you trust, create `.codex/config.toml` and add the local server command:
|
|
1579
|
+
|
|
1580
|
+
```toml
|
|
1581
|
+
[mcp_servers.airctrl]
|
|
1582
|
+
command = "npx"
|
|
1583
|
+
args = ["-y", "@airctrl/mcp"]
|
|
1584
|
+
```
|
|
1585
|
+
|
|
1586
|
+
Use your user `config.toml` when you want the integration in all of your projects. Add the selected human or Service Account identity through Codex's local secure configuration, following [MCP setup](https://docs.airctrl.dev/mcp/setup). Do not mix the two identity modes.
|
|
1587
|
+
|
|
1588
|
+
You can also add a local server in the Codex desktop app through **Settings** > **MCP Servers**. Choose **STDIO** and enter the same command and arguments.
|
|
1589
|
+
|
|
1590
|
+
### Verify the connection
|
|
1591
|
+
|
|
1592
|
+
In a Codex chat, send this request:
|
|
1593
|
+
|
|
1594
|
+
```text
|
|
1595
|
+
Check the AIRCTRL connection. Tell me which API URL and identity type are configured. Do not read or reveal any record values.
|
|
1596
|
+
```
|
|
1597
|
+
|
|
1598
|
+
Codex should call the safe AIRCTRL status tool. If you use a Service Account, ask it to list metadata from one assigned project instead of asking for accounts.
|
|
1599
|
+
|
|
1600
|
+
### Use it safely
|
|
1601
|
+
|
|
1602
|
+
Keep the configuration in a trusted project. State the account, project, and resource you intend to use. Ask for a read before any write, and review the proposed operation before approving it. Never include a token, passphrase, provider key, or decrypted value in chat.
|
|
1603
|
+
|
|
1604
|
+
### Troubleshoot or remove it
|
|
1605
|
+
|
|
1606
|
+
Open the MCP server list in Codex to confirm that AIRCTRL is enabled. If it cannot start, verify Node.js and the local secure configuration. A `403` response means the selected identity lacks permission; changing an ID cannot grant it.
|
|
1607
|
+
|
|
1608
|
+
Delete the `airctrl` entry from the relevant `config.toml`, or remove the server in **Settings** > **MCP Servers**. See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for client-specific options.
|
|
1609
|
+
## Connect Cursor
|
|
1610
|
+
|
|
1611
|
+
Cursor starts AIRCTRL as a local MCP process. Read [MCP setup](https://docs.airctrl.dev/mcp/setup) first to choose the right identity and keep its sensitive configuration outside your project.
|
|
1612
|
+
|
|
1613
|
+
### Add AIRCTRL to one project
|
|
1614
|
+
|
|
1615
|
+
Create `.cursor/mcp.json` in the project root and add the local server command:
|
|
1616
|
+
|
|
1617
|
+
```json
|
|
1618
|
+
{
|
|
1619
|
+
"mcpServers": {
|
|
1620
|
+
"airctrl": {
|
|
1621
|
+
"command": "npx",
|
|
1622
|
+
"args": ["-y", "@airctrl/mcp"]
|
|
1623
|
+
}
|
|
1624
|
+
}
|
|
1625
|
+
}
|
|
1626
|
+
```
|
|
1627
|
+
|
|
1628
|
+
Use Cursor's user configuration when you want AIRCTRL available across your projects. Add the selected human or Service Account identity through Cursor's local secure configuration, following [MCP setup](https://docs.airctrl.dev/mcp/setup). Do not mix the two identity modes.
|
|
1629
|
+
|
|
1630
|
+
### Verify the connection
|
|
1631
|
+
|
|
1632
|
+
Open Cursor's MCP server settings and confirm that AIRCTRL is enabled. Then ask the agent:
|
|
1633
|
+
|
|
1634
|
+
```text
|
|
1635
|
+
Check the AIRCTRL connection. Tell me which API URL and identity type are configured. Do not read or reveal any record values.
|
|
1636
|
+
```
|
|
1637
|
+
|
|
1638
|
+
Cursor should call the safe AIRCTRL status tool. If you use a Service Account, ask it to list metadata from one assigned project instead of asking for accounts.
|
|
1639
|
+
|
|
1640
|
+
### Use it safely
|
|
1641
|
+
|
|
1642
|
+
State the account, project, and resource you intend to use. Ask for a read before any write. Review the proposed operation before approving it. Never include a token, passphrase, provider key, or decrypted value in chat.
|
|
1643
|
+
|
|
1644
|
+
### Troubleshoot or remove it
|
|
1645
|
+
|
|
1646
|
+
Use Cursor's MCP settings to review the server status and logs. If the server does not start, verify Node.js and the local secure configuration. A `403` response means the selected identity lacks permission; changing an ID cannot grant it.
|
|
1647
|
+
|
|
1648
|
+
Remove the `airctrl` entry from `.cursor/mcp.json`, or remove it in the MCP settings. See the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) for client-specific options.
|
|
1649
|
+
## Connect VS Code
|
|
1650
|
+
|
|
1651
|
+
Visual Studio Code starts AIRCTRL as a local MCP process. Read [MCP setup](https://docs.airctrl.dev/mcp/setup) first to choose the right identity and keep its sensitive configuration outside your project.
|
|
1652
|
+
|
|
1653
|
+
### Add AIRCTRL to one workspace
|
|
1654
|
+
|
|
1655
|
+
Create `.vscode/mcp.json` in the workspace and add the local server command:
|
|
1656
|
+
|
|
1657
|
+
```json
|
|
1658
|
+
{
|
|
1659
|
+
"servers": {
|
|
1660
|
+
"airctrl": {
|
|
1661
|
+
"command": "npx",
|
|
1662
|
+
"args": ["-y", "@airctrl/mcp"]
|
|
1663
|
+
}
|
|
1664
|
+
}
|
|
1665
|
+
}
|
|
1666
|
+
```
|
|
1667
|
+
|
|
1668
|
+
You can also use **MCP: Add Server** from the Command Palette and select the workspace or your user profile. Add the selected human or Service Account identity through VS Code's local secure configuration, following [MCP setup](https://docs.airctrl.dev/mcp/setup). Do not mix the two identity modes.
|
|
1669
|
+
|
|
1670
|
+
### Verify the connection
|
|
1671
|
+
|
|
1672
|
+
Open **MCP: List Servers** from the Command Palette. Review the command, trust AIRCTRL, and confirm that it starts. Then ask the agent:
|
|
1673
|
+
|
|
1674
|
+
```text
|
|
1675
|
+
Check the AIRCTRL connection. Tell me which API URL and identity type are configured. Do not read or reveal any record values.
|
|
1676
|
+
```
|
|
1677
|
+
|
|
1678
|
+
VS Code should call the safe AIRCTRL status tool. If you use a Service Account, ask it to list metadata from one assigned project instead of asking for accounts.
|
|
1679
|
+
|
|
1680
|
+
### Use it safely
|
|
1681
|
+
|
|
1682
|
+
Review a workspace configuration before trusting it. State the account, project, and resource you intend to use. Ask for a read before any write, and review the proposed operation before approving it. Never include a token, passphrase, provider key, or decrypted value in chat.
|
|
1683
|
+
|
|
1684
|
+
### Troubleshoot or remove it
|
|
1685
|
+
|
|
1686
|
+
Use **MCP: List Servers** to review AIRCTRL's status. If it cannot start, verify Node.js and the local secure configuration. A `403` response means the selected identity lacks permission; changing an ID cannot grant it.
|
|
1687
|
+
|
|
1688
|
+
Remove the `airctrl` entry from `.vscode/mcp.json`, or remove it through the MCP commands. See the [VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers) for client-specific options.
|
|
1689
|
+
## Connect Warp
|
|
1690
|
+
|
|
1691
|
+
Warp starts AIRCTRL as a local MCP process. Read [MCP setup](https://docs.airctrl.dev/mcp/setup) first to choose the right identity and keep its sensitive configuration outside your project.
|
|
1692
|
+
|
|
1693
|
+
### Add AIRCTRL in Warp
|
|
1694
|
+
|
|
1695
|
+
Open **Settings** > **Agents** > **MCP servers** in Warp, then add a local server. Set the command to `npx` and pass `-y @airctrl/mcp` as its arguments.
|
|
1696
|
+
|
|
1697
|
+
Add the selected human or Service Account identity through Warp's local secret configuration, following [MCP setup](https://docs.airctrl.dev/mcp/setup). Do not mix the two identity modes. Warp can sync a server configuration between your machines, but it does not sync its sensitive configuration. Configure that separately on every machine that runs AIRCTRL.
|
|
1698
|
+
|
|
1699
|
+
### Verify the connection
|
|
1700
|
+
|
|
1701
|
+
Open the AIRCTRL MCP server in Warp and confirm that it is enabled. Then ask the agent:
|
|
1702
|
+
|
|
1703
|
+
```text
|
|
1704
|
+
Check the AIRCTRL connection. Tell me which API URL and identity type are configured. Do not read or reveal any record values.
|
|
1705
|
+
```
|
|
1706
|
+
|
|
1707
|
+
Warp should call the safe AIRCTRL status tool. If you use a Service Account, ask it to list metadata from one assigned project instead of asking for accounts.
|
|
1708
|
+
|
|
1709
|
+
### Use it safely
|
|
1710
|
+
|
|
1711
|
+
State the account, project, and resource you intend to use. Ask for a read before any write. Review the proposed operation before approving it. Never include a token, passphrase, provider key, or decrypted value in chat.
|
|
1712
|
+
|
|
1713
|
+
### Troubleshoot or remove it
|
|
1714
|
+
|
|
1715
|
+
Open **Settings** > **Agents** > **MCP servers** and verify the AIRCTRL command. If it cannot start, verify Node.js and the local secure configuration. A `403` response means the selected identity lacks permission; changing an ID cannot grant it.
|
|
1716
|
+
|
|
1717
|
+
Disable or remove AIRCTRL from the same settings page when you no longer need it. See the [Warp MCP documentation](https://docs.warp.dev/reference/cli/mcp-servers) for client-specific options.
|
|
1718
|
+
|
|
1719
|
+
## License
|
|
1720
|
+
|
|
1721
|
+
Proprietary software. All rights reserved.
|