@airctrl/mcp 0.2.0 → 0.4.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 CHANGED
@@ -14,6 +14,39 @@ npx --yes @airctrl/mcp
14
14
 
15
15
  Requires Node.js 22.x.
16
16
 
17
+ ## Current release
18
+
19
+ **Coordinated package version:** `0.4.0`
20
+
21
+ ### SDK
22
+
23
+ - Added `OAuthPartnerClient`, PKCE generation, authorization-code exchange, rotating refresh tokens, and token revocation for confidential partner backends.
24
+ - Added provider resolution, provider-key validation, live model discovery, entitlement preflight, atomic protection provisioning, and installation-bound protection reads and updates.
25
+ - Added provider-key rotation, runtime-token rotation, revoke, and reactivate lifecycle operations with typed idempotency and error handling.
26
+ - Added public multi-organization OAuth Apps: one publisher-owned Client ID can create isolated installations inside customer-selected AIRCTRL organizations.
27
+ - Added `listProtectionLogs()` and `getProtectionSpend()` with dedicated least-privilege scopes and strict installation/protection binding.
28
+ - Added stable cursor pagination and canonical account, project, gateway, token, principal, trace, and span correlation across request-log, usage, and audit feeds.
29
+ - Added OpenTelemetry body-export controls and shared gateway connection types aligned with the public API contract.
30
+
31
+ ### CLI
32
+
33
+ - Added opaque cursor support to gateway logs, provider-key access, usage logs, record alerts, and record access commands.
34
+ - Added the `audit-events` command with cursor, action, actor, and date filters.
35
+ - Added OpenTelemetry request/response body-export configuration while preserving the existing header-custody contract.
36
+
37
+ ### MCP
38
+
39
+ - Added opaque cursor inputs to gateway, usage, record-alert, and record-access tools.
40
+ - Added `list_record_audit` with stable filters and pagination.
41
+ - Added OpenTelemetry body-export configuration and aligned pagination limits with the API contract.
42
+
43
+ ### Release engineering
44
+
45
+ - Kept SDK, CLI, and MCP manifests, internal dependencies, exported version constants, generated READMEs, and tarball names aligned at `0.4.0`.
46
+ - Build `@airctrl/client-contracts` before OpenAPI generation and full-stack certification so clean release runners never depend on cached workspace output.
47
+ - Expanded package verification across the public API, generated examples, installed-package behavior, exact tarballs, and Linux, Windows, and macOS certification.
48
+ - Kept `@airctrl/crypto` and `@airctrl/secrets` private and bundled the required runtime into the public SDK.
49
+
17
50
  ## MCP setup
18
51
 
19
52
  `@airctrl/mcp` runs locally on your machine or in infrastructure you control. It uses `@airctrl/sdk` for AIRCTRL operations.
@@ -205,6 +238,26 @@ any listed operation when the Service Account lacks the required custom-role per
205
238
  | `update_project` | `accountId`, `projectId`, `name`, `description`, `isActive` | Replace project name, description and active state. |
206
239
  | `set_project_archive` | `accountId`, `projectId`, `archived` | Archive or restore one project. |
207
240
 
241
+ ### Groups and access material
242
+
243
+ These tools are human-only. Team+ and RBAC apply; Service Accounts cannot manage or join human groups. Read [Groups and effective access](https://docs.airctrl.dev/guides/projects#groups-and-effective-access) before changing membership.
244
+
245
+ | Tool | Inputs | Purpose |
246
+ |---|---|---|
247
+ | `list_groups` | `accountId`, `projectId` | List groups in the project context and their current grants. |
248
+ | `list_record_group_grants` | `accountId`, `recordId` | Read group sharing options and caller capabilities. |
249
+ | `create_group` | `accountId`, `projectId`, `name`; optional `description` | Create a reusable account group without granting a project role. |
250
+ | `update_group` | `accountId`, `groupId`, `name`; optional `description` | Replace name and description; omission clears description. |
251
+ | `delete_group` | `accountId`, `groupId` | Delete the group while preserving independent access paths. |
252
+ | `list_group_members` | `accountId`, `groupId` | List current members, not candidate users. |
253
+ | `add_group_member` | `accountId`, `groupId`, `userId` | Add membership across existing group grants. |
254
+ | `remove_group_member` | `accountId`, `groupId`, `userId` | Remove only this membership and reconcile effective access. |
255
+ | `grant_project_group` | `accountId`, `projectId`, `groupId`, `roleId` | Grant an existing delegable project role. |
256
+ | `revoke_project_group` | `accountId`, `projectId`, `groupId`, `roleId` | Revoke only this project/group/role assignment. |
257
+ | `reconcile_group_access` | `accountId`; optional `projectIds` | Attempt pending material repair with the configured local vault. |
258
+
259
+ 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.
260
+
208
261
  ### Service Account metadata
209
262
 
210
263
  | Tool | Inputs | Purpose |
@@ -219,40 +272,55 @@ These metadata tools are human-only. Service Account creation, state changes, cr
219
272
  | Tool | Inputs | Purpose |
220
273
  |---|---|---|
221
274
  | `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. |
275
+ | `get_secret` | `recordId`; optional `environment` | Decrypt one General or selected Environment value locally. |
276
+ | `read_record` | `recordId`; optional `scope`, `environment` | Read selected record sections and only the selected secret value. `fields` returns its complete decrypted field map. |
277
+ | `get_all` | `projectId`; optional `environment` | Decrypt accessible General or selected Environment values in one project. |
225
278
  | `list_secret_types` | None | List supported record formats and field definitions. |
226
279
  | `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. |
280
+ | `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. |
281
+ | `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. |
229
282
 
230
283
  ### Record lifecycle and sharing
231
284
 
232
285
  | Tool | Inputs | Purpose |
233
286
  |---|---|---|
234
- | `update_record_metadata` | `recordId`; at least one of `name`, `tags`, `secretDueAt`, `rotationIntervalDays` | Change safe record metadata. |
287
+ | `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. |
235
288
  | `set_record_archive` | `recordId`, `archived` | Archive or restore a record. |
236
289
  | `transfer_record_ownership` | `recordId`, `newOwnerUserId` | Transfer record ownership to an eligible user. |
237
290
  | `list_record_versions` | `recordId` | List record version history. |
238
- | `rollback_record` | `recordId`, `targetVersionId` | Restore an earlier encrypted version. |
291
+ | `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. |
239
292
  | `rotate_record` | `recordId` | Rotate the record key and encrypted value locally. |
240
293
  | `share_record_user` | `recordId`, `userId`; optional `permission` | Share a record with one user. |
241
294
  | `share_record_service_account` | `accountId`, `recordId`, `serviceAccountId` | Share a record with one Service Account. |
242
295
  | `share_record_group` | `recordId`, `groupId` | Share a record with a group. |
243
- | `revoke_record_user` | `recordId`, `userId` | Remove one user's record access. |
296
+ | `revoke_record_user` | `recordId`, `userId` | Remove the direct user grant; preserve independent access paths. |
244
297
  | `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. |
298
+ | `revoke_record_group` | `recordId`, `groupId` | Remove the group grant; preserve independent access paths. |
246
299
 
247
300
  ### Record audit
248
301
 
249
302
  | Tool | Inputs | Purpose |
250
303
  |---|---|---|
251
304
  | `read_record_audit` | `recordId`; optional `limit` | Read audit events for one record. |
305
+ | `list_record_audit` | `recordId`; optional `cursor`, `action`, `actor`, `from`, `to`, `limit`, legacy `offset` | Read a stable filtered audit-event page. |
252
306
  | `list_record_anomalies` | Optional `accountId`, `scopeType`, `scopeId` | List unusual record events. |
253
307
  | `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. |
308
+ | `list_record_alerts` | Optional `accountId`, `scopeType`, `scopeId`, `cursor`, `limit`, legacy `offset` | Read the record alert feed. |
309
+ | `list_record_access` | Optional `accountId`, `scopeType`, `scopeId`, `cursor`, `limit`, legacy `offset`, `actions` | Read the record access feed. |
310
+
311
+ Ask an agent for a bounded page and keep the returned cursor opaque:
312
+
313
+ ```text
314
+ List the first 25 record.update audit events for record
315
+ 00000000-0000-4000-8000-000000000020 where the actor contains "david".
316
+ Return pagination.next_cursor without decoding it.
317
+ ```
318
+
319
+
320
+
321
+ **MCP tool used:** `list_record_audit`
322
+
323
+
256
324
 
257
325
  ### Providers and gateway setup
258
326
 
@@ -266,12 +334,12 @@ These metadata tools are human-only. Service Account creation, state changes, cr
266
334
  | `rename_provider_credential` | `accountId`, `credentialId`, `label` | Change a provider credential label. |
267
335
  | `revoke_provider_credential` | `accountId`, `credentialId` | Revoke a provider credential. |
268
336
  | `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. |
337
+ | `create_gateway` | `accountId`, `projectId`, `name`; optional `slug`, `credentialBindings` | Create a gateway, optionally with explicit credential/model bindings. |
338
+ | `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. |
339
+ | `get_connection_config` | `gatewayId` | Return compatibility and native OpenAI, Anthropic, Gemini, Mistral and OpenRouter URLs, plus supported realtime WebSocket URLs. |
340
+ | `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. |
341
+ | `set_gateway_settings` | `accountId`, `gatewayId`; at least one optional settings field | Update limits, logging, guardrails or allowed models. |
342
+ | `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. |
275
343
  | `delete_gateway` | `accountId`, `gatewayId` | Disable a gateway and revoke its tokens. |
276
344
 
277
345
  ### Gateway tokens
@@ -288,10 +356,10 @@ These metadata tools are human-only. Service Account creation, state changes, cr
288
356
 
289
357
  | Tool | Inputs | Purpose |
290
358
  |---|---|---|
291
- | `read_usage` | `gatewayId`; optional `since`, `provider`, `model`, `status`, `limit`, `offset` | Read filtered request metadata for one gateway. |
359
+ | `read_usage` | `gatewayId`; optional `since`, `provider`, `model`, `status`, `cursor`, `limit`, legacy `offset` | Read filtered request metadata for one gateway. |
292
360
  | `read_gateway_log` | `gatewayId`, `logId` | Read stored request and response bodies for one gateway log. |
293
361
  | `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. |
362
+ | `list_usage_logs` | `projectId`; optional `since`, `provider`, `model`, `status`, `gatewayId`, `cursor`, `limit`, legacy `offset` | List usage across a project. |
295
363
  | `read_usage_log` | `projectId`, `logId` | Read one project's stored request and response bodies. |
296
364
  | `read_usage_spend` | `projectId` | Compare spend with effective limits. |
297
365
  | `read_usage_metrics` | `projectId`; optional `since`, `bucket` | Read request, error, token, latency and spend metrics. |
@@ -303,9 +371,9 @@ These metadata tools are human-only. Service Account creation, state changes, cr
303
371
  - IDs are UUID strings. Copy them from AIRCTRL instead of asking an agent to guess them.
304
372
  - Dates and timestamps use ISO 8601. `day` uses `YYYY-MM-DD`; `since` accepts a complete timestamp.
305
373
  - `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.
374
+ - 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.
307
375
  - `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.
376
+ - 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.
309
377
  - `accountId` selects the account. It does not grant access to it.
310
378
  - `projectId`, `recordId`, `gatewayId`, `credentialId` and `tokenId` select resources. AIRCTRL still checks RBAC and resource access.
311
379
  - Optional booleans must be real JSON booleans such as `true`, not strings such as `"true"`.
@@ -354,6 +422,23 @@ only for this task. Do not print it, log it or include it in your final response
354
422
 
355
423
 
356
424
 
425
+ #### Read one Environment value locally
426
+
427
+ For a By Environment record, request one value explicitly:
428
+
429
+ ```text
430
+ Read only the Staging value of record
431
+ "00000000-0000-4000-8000-000000000020". Do not read General, Development
432
+ or Production. Use the value only for this approved task; do not repeat it
433
+ in your response.
434
+ ```
435
+
436
+
437
+
438
+ **MCP tool used:** `get_secret` with `environment: 'staging'`
439
+
440
+
441
+
357
442
  #### Create a generated password record
358
443
 
359
444
 
@@ -364,9 +449,10 @@ only for this task. Do not print it, log it or include it in your final response
364
449
 
365
450
  ```text
366
451
  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.
452
+ "00000000-0000-4000-8000-000000000010". Set the service name to "Database"
453
+ and username to "app_user", then generate a 32-character password locally.
454
+ Before creating it, confirm the project ID, name, format and non-secret fields.
455
+ Never print the generated password.
370
456
  ```
371
457
 
372
458
 
@@ -375,6 +461,24 @@ print the generated password.
375
461
 
376
462
 
377
463
 
464
+ #### Create a generated Environment record
465
+
466
+ The same tool can create a single Staging value without inventing another record or exposing generated material in the prompt:
467
+
468
+ ```text
469
+ Create an SSH record named "Deployment key" in project
470
+ "00000000-0000-4000-8000-000000000010" for Staging only. Generate the key
471
+ locally with host "stage.example.invalid" and username "deploy". Show
472
+ the project, name, format and Environment before asking for my confirmation.
473
+ Do not print the generated private key.
474
+ ```
475
+
476
+
477
+
478
+ **MCP tool used:** `create_record` with `environment: 'staging'` and `generate: true`
479
+
480
+
481
+
378
482
  #### Set up a gateway from an environment variable
379
483
 
380
484
 
@@ -437,6 +541,19 @@ After confirmation, revoke only that token and report its final status.
437
541
 
438
542
 
439
543
 
544
+ ### OAuth partner Apps
545
+
546
+ The MCP server has no OAuth App credential mode, authorization-code flow, or
547
+ installation/protection lifecycle tools. Do not place OAuth client secrets, authorization codes,
548
+ access tokens, or refresh tokens in MCP configuration or an agent conversation. Neither is a
549
+ confidential partner token store, and a hosted MCP would violate the partner-backend boundary.
550
+
551
+ Implement OAuth partner flows through direct HTTP/OpenAPI or `OAuthPartnerClient` in the partner's
552
+ confidential backend. See [OAuth partner integrations](https://docs.airctrl.dev/guides/oauth-partner-integrations),
553
+ [OAuth protocol](https://docs.airctrl.dev/reference/oauth-protocol), and
554
+ [OAuth protection API](https://docs.airctrl.dev/reference/oauth-protections). MCP may manage ordinary gateways with a
555
+ separately authorized human PAT; those tools do not act as an OAuth installation.
556
+
440
557
  ### Tool results
441
558
 
442
559
  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.
@@ -862,7 +979,7 @@ Give Service Account "00000000-0000-4000-8000-000000000040" access to record "00
862
979
  #### Share a record with a group
863
980
 
864
981
  ```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.
982
+ Share record "00000000-0000-4000-8000-000000000020" with group "00000000-0000-4000-8000-000000000060". Verify that both belong to the same account, then wait for my confirmation. Do not grant project access.
866
983
  ```
867
984
 
868
985
 
@@ -907,6 +1024,142 @@ Remove group "00000000-0000-4000-8000-000000000060" from record "00000000-0000-4
907
1024
 
908
1025
 
909
1026
 
1027
+ ### Groups
1028
+
1029
+ These prompts require a human PAT, Team+ and appropriate RBAC permissions. Replace all example IDs with verified IDs. A successful membership or role write can leave encrypted material pending; read [the access model](https://docs.airctrl.dev/guides/projects#groups-and-effective-access).
1030
+
1031
+ #### List context groups
1032
+
1033
+ ```text
1034
+ List groups associated with project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Show their IDs and current project grants. Do not change anything.
1035
+ ```
1036
+
1037
+
1038
+
1039
+ **MCP tool used:** `list_groups`
1040
+
1041
+
1042
+
1043
+ #### Read a record's group grants
1044
+
1045
+ ```text
1046
+ Show group sharing options and current grants for record "00000000-0000-4000-8000-000000000020" in account "00000000-0000-4000-8000-000000000001". Do not expose its secret.
1047
+ ```
1048
+
1049
+
1050
+
1051
+ **MCP tool used:** `list_record_group_grants`
1052
+
1053
+
1054
+
1055
+ #### Create a group
1056
+
1057
+ ```text
1058
+ Create a group named "Payments team" with description "Payments operators" through project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Do not grant it a project role. Show the inputs and wait for my confirmation.
1059
+ ```
1060
+
1061
+
1062
+
1063
+ **MCP tool used:** `create_group`
1064
+
1065
+
1066
+
1067
+ #### Rename a group
1068
+
1069
+ ```text
1070
+ Rename group "00000000-0000-4000-8000-000000000060" in account "00000000-0000-4000-8000-000000000001" to "Payments operators" and replace its description with "Payments access". Show both replacement values and wait for my confirmation.
1071
+ ```
1072
+
1073
+
1074
+
1075
+ **MCP tool used:** `update_group`
1076
+
1077
+
1078
+
1079
+ #### Delete a group
1080
+
1081
+ ```text
1082
+ Delete group "00000000-0000-4000-8000-000000000060" in account "00000000-0000-4000-8000-000000000001". Show its members and explain that independent access paths remain. Wait for my confirmation, then report the server's access changes and pending material without claiming every recipient is finished.
1083
+ ```
1084
+
1085
+
1086
+
1087
+ **MCP tool used:** `delete_group`
1088
+
1089
+
1090
+
1091
+ #### List group members
1092
+
1093
+ ```text
1094
+ List current members of group "00000000-0000-4000-8000-000000000060" in account "00000000-0000-4000-8000-000000000001". Include their IDs and onboarding state. Do not change anything.
1095
+ ```
1096
+
1097
+
1098
+
1099
+ **MCP tool used:** `list_group_members`
1100
+
1101
+
1102
+
1103
+ #### Add a group member
1104
+
1105
+ ```text
1106
+ Add user "00000000-0000-4000-8000-000000000050" to group "00000000-0000-4000-8000-000000000060" in account "00000000-0000-4000-8000-000000000001". Explain that existing group grants apply. Wait for my confirmation, then report pending material from the result.
1107
+ ```
1108
+
1109
+
1110
+
1111
+ **MCP tool used:** `add_group_member`
1112
+
1113
+
1114
+
1115
+ #### Remove a group member
1116
+
1117
+ ```text
1118
+ Remove user "00000000-0000-4000-8000-000000000050" from group "00000000-0000-4000-8000-000000000060" in account "00000000-0000-4000-8000-000000000001". Preserve independent access paths. Wait for my confirmation, then report remaining paths and any pending re-keying from the result.
1119
+ ```
1120
+
1121
+
1122
+
1123
+ **MCP tool used:** `remove_group_member`
1124
+
1125
+
1126
+
1127
+ #### Grant a project role to a group
1128
+
1129
+ ```text
1130
+ Assign role "00000000-0000-4000-8000-000000000070" to group "00000000-0000-4000-8000-000000000060" for project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Use exactly these verified IDs. Show the assignment and wait for my confirmation. Report pending encrypted material separately from authorization.
1131
+ ```
1132
+
1133
+
1134
+
1135
+ **MCP tool used:** `grant_project_group`
1136
+
1137
+
1138
+
1139
+ #### Revoke one project role from a group
1140
+
1141
+ ```text
1142
+ Revoke only role "00000000-0000-4000-8000-000000000070" assigned to group "00000000-0000-4000-8000-000000000060" for project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Do not revoke independent paths. Show the assignment and wait for my confirmation.
1143
+ ```
1144
+
1145
+
1146
+
1147
+ **MCP tool used:** `revoke_project_group`
1148
+
1149
+
1150
+
1151
+ #### Complete pending encrypted access
1152
+
1153
+ ```text
1154
+ Using the already configured local vault, attempt encrypted-material repair for project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001", including pending direct group-record shares in the account. Do not grant permissions or ask me to put a passphrase in this chat. Report attempted projects and errors; do not call attempts completed recipient access.
1155
+ ```
1156
+
1157
+
1158
+
1159
+ **MCP tool used:** `reconcile_group_access`
1160
+
1161
+
1162
+
910
1163
  ### Record audit
911
1164
 
912
1165
  #### Review one record's audit history
@@ -921,6 +1174,18 @@ Show the 25 most recent audit events for record "00000000-0000-4000-8000-0000000
921
1174
 
922
1175
 
923
1176
 
1177
+ #### Page and filter one record's audit history
1178
+
1179
+ ```text
1180
+ 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 so I can request the next page with the same filters.
1181
+ ```
1182
+
1183
+
1184
+
1185
+ **MCP tool used:** `list_record_audit`
1186
+
1187
+
1188
+
924
1189
  #### Find unusual record activity
925
1190
 
926
1191
  ```text
@@ -1090,7 +1355,7 @@ This workflow can add a provider credential, create a gateway and create a one-t
1090
1355
 
1091
1356
 
1092
1357
  ```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.
1358
+ 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", bind models "gpt-5" and "gpt-5-mini", and name the first gateway token "Local development". Explain every resource that will be created and wait for my confirmation.
1094
1359
  ```
1095
1360
 
1096
1361
 
@@ -1114,7 +1379,7 @@ Show me how to connect to gateway "00000000-0000-4000-8000-000000000030", includ
1114
1379
  #### Change gateway routing
1115
1380
 
1116
1381
  ```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.
1382
+ Attach provider credential "00000000-0000-4000-8000-000000000200" to models "gpt-5" and "gpt-5-mini" on gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Show the current and proposed bindings, then wait for my confirmation.
1118
1383
  ```
1119
1384
 
1120
1385
 
@@ -1126,7 +1391,7 @@ Attach provider credential "00000000-0000-4000-8000-000000000200" to model "gpt-
1126
1391
  #### Change gateway limits and behavior
1127
1392
 
1128
1393
  ```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.
1394
+ 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, and guardrails in flag mode. Show every proposed change and wait for my confirmation.
1130
1395
  ```
1131
1396
 
1132
1397
 
@@ -1138,6 +1403,8 @@ For gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-400
1138
1403
  #### Detach a provider credential
1139
1404
 
1140
1405
  ```text
1406
+ Remove model "gpt-5" from provider credential "00000000-0000-4000-8000-000000000071" on gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Keep the credential and its other models attached. Show the resulting bindings, then wait for my approval.
1407
+
1141
1408
  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
1409
  ```
1143
1410
 
@@ -1322,7 +1589,7 @@ Show the OpenTelemetry export settings for gateway "00000000-0000-4000-8000-0000
1322
1589
  #### Change OpenTelemetry settings
1323
1590
 
1324
1591
  ```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.
1592
+ Enable OpenTelemetry metrics and traces for gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Request events are automatic while export is enabled. Include request/response bodies only if gateway Log bodies is enabled. Send them to the base endpoint "https://otel.example.com" and read headers from "OTEL_EXPORT_HEADERS". Show the destination and enabled data, then wait for my confirmation.
1326
1593
  ```
1327
1594
 
1328
1595
 
@@ -1497,7 +1764,7 @@ Replace provider credential "00000000-0000-4000-8000-000000000071" in account "0
1497
1764
  ### Configure OpenTelemetry and verify safe state
1498
1765
 
1499
1766
  ```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.
1767
+ 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 the base endpoint "https://otel.example.com" using headers from "OTEL_EXPORT_HEADERS"; request events are automatic while export is enabled. Include bodies only when gateway Log bodies is enabled. Wait for my confirmation, apply the change, and report only the final safe settings.
1501
1768
  ```
1502
1769
 
1503
1770
 
package/dist/config.js CHANGED
@@ -1,6 +1,7 @@
1
1
  const present = (value) => value !== undefined && value.trim() !== '';
2
2
  const defined = (value) => value !== undefined;
3
3
  function isCanonicalB64(value, expectedBytes) {
4
+ // nosemgrep: nodejs_scan.javascript-dos-rule-regex_dos -- anchored canonical base64 validation is linear and followed by decode/re-encode verification.
4
5
  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value))
5
6
  return false;
6
7
  const decoded = Buffer.from(value, 'base64');
package/dist/index.js CHANGED
@@ -14,7 +14,7 @@ import { registerTools } from './tools.js';
14
14
  */
15
15
  const config = loadConfig();
16
16
  const client = createClient(createMcpClientOptions(config));
17
- const server = new McpServer({ name: 'airctrl', version: '0.2.0' });
17
+ const server = new McpServer({ name: 'airctrl', version: '0.4.0' });
18
18
  registerTools(server, client, config);
19
19
  server.registerTool('airctrl_status', {
20
20
  title: 'AIRCTRL MCP status',
package/dist/tools.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { generateSecret, canGenerate, isSecretFormat, SECRET_FORMATS, TEMPLATES, AirctrlError, } from '@airctrl/sdk';
2
+ import { generateSecret, canGenerate, isSecretFormat, SECRET_FORMATS, RECORD_ENVIRONMENTS, TEMPLATES, AirctrlError, buildGatewayConnectionConfig, } from '@airctrl/sdk';
3
3
  /**
4
4
  * Build the one shared error type (SSOT R8) from the MCP's `(code, message, status)` call convention.
5
5
  * The transport + error now live only in `@airctrl/sdk`; this is a thin arg-order adapter, not a
@@ -15,11 +15,12 @@ function ok(data) {
15
15
  }
16
16
  /** Error de un tool: mensaje legible + `isError` para que el agente lo vea. */
17
17
  function fail(e) {
18
- const msg = e instanceof AirctrlError
19
- ? `${e.code}: ${e.message}`
20
- : e instanceof Error
21
- ? e.message
22
- : 'unknown error';
18
+ if (e instanceof AirctrlError) {
19
+ return { content: [{ type: 'text', text: `AIRCTRL error — ${JSON.stringify({ code: e.code, message: e.message, details: e.details })}` }], isError: true };
20
+ }
21
+ const msg = e instanceof Error
22
+ ? e.message
23
+ : 'unknown error';
23
24
  return { content: [{ type: 'text', text: `AIRCTRL error — ${msg}` }], isError: true };
24
25
  }
25
26
  async function run(fn) {
@@ -37,14 +38,28 @@ async function run(fn) {
37
38
  * `create_gateway_token` / `setup_gateway`).
38
39
  */
39
40
  function buildConnectionConfig(config, gw) {
40
- const base = `${config.apiUrl}/gw/${gw.slug}`;
41
+ const connection = buildGatewayConnectionConfig(config.apiUrl, gw.slug);
41
42
  return {
42
43
  gateway: gw.name,
43
44
  slug: gw.slug,
44
- openai_sdk: { base_url: `${base}/compat`, note: 'OpenAI SDK: base_url here, api_key = gateway token' },
45
- openai_native: `${base}/openai/v1/chat/completions`,
45
+ openai_sdk: { base_url: connection.compatBaseUrl, note: 'OpenAI SDK: base_url here, api_key = gateway token' },
46
+ // Backward-compatible full chat endpoint retained for existing consumers.
47
+ openai_native: `${connection.openaiBaseUrl}/chat/completions`,
48
+ native: {
49
+ openai: connection.openaiBaseUrl,
50
+ anthropic: connection.anthropicBaseUrl,
51
+ gemini: connection.geminiBaseUrl,
52
+ mistral: connection.mistralBaseUrl,
53
+ openrouter: connection.openrouterBaseUrl,
54
+ hitheo: connection.hitheoBaseUrl,
55
+ },
56
+ realtime: {
57
+ openai: `${connection.openaiRealtimeUrl}?model=<model>`,
58
+ gemini: connection.geminiRealtimeUrl,
59
+ mistral: `${connection.mistralRealtimeUrl}?model=<model>`,
60
+ },
46
61
  claude_code: {
47
- ANTHROPIC_BASE_URL: `${base}/anthropic`,
62
+ ANTHROPIC_BASE_URL: connection.anthropicBaseUrl,
48
63
  ANTHROPIC_AUTH_TOKEN: 'sk-actrl-*** (from create_gateway_token or setup_gateway)',
49
64
  },
50
65
  };
@@ -156,6 +171,51 @@ function serverForPrincipal(server, config) {
156
171
  }
157
172
  export function registerTools(inputServer, client, config) {
158
173
  const server = serverForPrincipal(inputServer, config);
174
+ const recordEnvironment = z.enum(RECORD_ENVIRONMENTS);
175
+ const groupScope = { accountId: z.string().uuid() };
176
+ const groupIdentity = { ...groupScope, groupId: z.string().uuid() };
177
+ const groupMember = { ...groupIdentity, userId: z.string().uuid() };
178
+ const groupGrant = { ...groupIdentity, projectId: z.string().uuid(), roleId: z.string().uuid() };
179
+ const groupFields = { name: z.string(), description: z.string().optional() };
180
+ server.registerTool('list_record_group_grants', {
181
+ title: 'List record group grants', description: 'Read group grants and sharing capabilities from the server. Requires records:read and Team+.',
182
+ inputSchema: { ...groupScope, recordId: z.string().uuid() },
183
+ }, ({ accountId, recordId }) => run(() => client.getRecordGroupCatalog(recordId, { accountId })));
184
+ server.registerTool('list_groups', {
185
+ title: 'List project groups', description: 'List existing group contexts for a project. Requires groups:list.',
186
+ inputSchema: { ...groupScope, projectId: z.string().uuid() },
187
+ }, ({ accountId, projectId }) => run(() => client.listGroups(projectId, { accountId })));
188
+ server.registerTool('create_group', {
189
+ title: 'Create group', description: 'Create a reusable account group in a project context. Does not grant a project role.',
190
+ inputSchema: { ...groupScope, projectId: z.string().uuid(), ...groupFields },
191
+ }, ({ accountId, projectId, ...input }) => run(() => client.createGroup(projectId, input, { accountId })));
192
+ server.registerTool('update_group', {
193
+ title: 'Update group', description: 'Replace group name and description. Omitted description becomes empty.',
194
+ inputSchema: { ...groupIdentity, ...groupFields },
195
+ }, ({ accountId, groupId, ...input }) => run(() => client.updateGroup(groupId, input, { accountId })));
196
+ server.registerTool('delete_group', {
197
+ title: 'Delete group', description: 'Delete group intent and reconcile access on the server, preserving other access paths.', inputSchema: groupIdentity,
198
+ }, ({ accountId, groupId }) => run(() => client.deleteGroup(groupId, { accountId })));
199
+ server.registerTool('list_group_members', {
200
+ title: 'List group members', description: 'List current group members.', inputSchema: groupIdentity,
201
+ }, ({ accountId, groupId }) => run(() => client.listGroupMembers(groupId, { accountId })));
202
+ server.registerTool('add_group_member', {
203
+ title: 'Add group member', description: 'Add durable membership. The response reports pending material; reconcile_group_access attempts sealing.', inputSchema: groupMember,
204
+ }, ({ accountId, groupId, userId }) => run(() => client.addGroupMember(groupId, userId, { accountId })));
205
+ server.registerTool('remove_group_member', {
206
+ title: 'Remove group member', description: 'Remove membership; wrappers are removed only when no authorized access path remains.', inputSchema: groupMember,
207
+ }, ({ accountId, groupId, userId }) => run(() => client.removeGroupMember(groupId, userId, { accountId })));
208
+ server.registerTool('grant_project_group', {
209
+ title: 'Grant project role to group', description: 'Grant an existing role to a group. The server checks delegation and every affected membership.', inputSchema: groupGrant,
210
+ }, ({ accountId, projectId, groupId, roleId }) => run(() => client.grantProjectGroup(projectId, groupId, roleId, { accountId })));
211
+ server.registerTool('revoke_project_group', {
212
+ title: 'Revoke project role from group', description: 'Revoke one grant without revoking independent access paths.', inputSchema: groupGrant,
213
+ }, ({ accountId, projectId, groupId, roleId }) => run(() => client.revokeProjectGroup(projectId, groupId, roleId, { accountId })));
214
+ server.registerTool('reconcile_group_access', {
215
+ title: 'Reconcile group access material',
216
+ description: 'Use the configured local vault to attempt existing project-key and group-record repair. Optional projectIds restrict projects, not direct group-record repairs in the account. Returns attempted IDs, not proof of complete access. Never grants permissions. Errors retain code/message/details.',
217
+ inputSchema: { ...groupScope, projectIds: z.array(z.string().uuid()).optional() },
218
+ }, input => run(() => client.reconcileGroupAccess({ ...input, vaultPassword: recordUnlockPassword(config) })));
159
219
  server.registerTool('list_accounts', {
160
220
  title: 'List accessible accounts',
161
221
  description: 'List the AIRCTRL accounts the authenticated developer can access. This discovers context only; it does not administer an account.',
@@ -238,9 +298,6 @@ export function registerTools(inputServer, client, config) {
238
298
  projectId: z.string().uuid(),
239
299
  name: z.string().min(1).max(100),
240
300
  slug: z.string().max(64).optional(),
241
- defaultProviderId: z.string().uuid().nullable().optional(),
242
- defaultModel: z.string().max(200).nullable().optional(),
243
- credentialIds: z.array(z.string().uuid()).optional(),
244
301
  credentialBindings: z.array(z.object({
245
302
  credentialId: z.string().uuid(),
246
303
  modelId: z.string().min(1).max(200),
@@ -304,36 +361,27 @@ export function registerTools(inputServer, client, config) {
304
361
  }, ({ accountId, credentialId, apiKeyEnv }) => run(() => client.rotateProviderCredential(credentialId, resolveProviderKeyEnv(apiKeyEnv), { accountId })));
305
362
  server.registerTool('set_routing', {
306
363
  title: 'Set gateway routing',
307
- description: 'Update gateway metadata/default routing and optionally attach a provider credential to one supported model. ' +
308
- 'When attachCredentialId is present, defaultModel must be the model for that binding.',
364
+ description: 'Update gateway metadata and optionally attach one provider credential to multiple exact models.',
309
365
  inputSchema: {
310
366
  accountId: z.string().uuid(),
311
367
  gatewayId: z.string().uuid(),
312
368
  name: z.string().min(1).max(100).optional(),
313
369
  isActive: z.boolean().optional(),
314
- defaultProviderId: z.string().uuid().nullable().optional(),
315
- defaultModel: z.string().max(200).nullable().optional(),
316
370
  attachCredentialId: z.string().uuid().optional(),
371
+ modelIds: z.array(z.string().min(1).max(200)).min(1).optional(),
317
372
  },
318
- }, ({ accountId, gatewayId, name, isActive, defaultProviderId, defaultModel, attachCredentialId }) => run(async () => {
319
- if (attachCredentialId && (typeof defaultModel !== 'string' || defaultModel.length === 0)) {
320
- throw new Error('defaultModel is required when attachCredentialId is provided');
373
+ }, ({ accountId, gatewayId, name, isActive, attachCredentialId, modelIds }) => run(async () => {
374
+ if ((attachCredentialId === undefined) !== (modelIds === undefined)) {
375
+ throw new Error('attachCredentialId and modelIds must be provided together');
321
376
  }
322
377
  const attached = attachCredentialId
323
- ? await client.attachGatewayCredential(gatewayId, attachCredentialId, defaultModel, { accountId })
378
+ ? await client.attachGatewayCredential(gatewayId, attachCredentialId, modelIds, { accountId })
324
379
  : null;
325
- // The backend only accepts a default route that already has a validated
326
- // credential/model binding, so attach first and then choose it as the
327
- // default when the caller supplied the provider explicitly.
328
380
  const patch = {};
329
381
  if (name !== undefined)
330
382
  patch.name = name;
331
383
  if (isActive !== undefined)
332
384
  patch.isActive = isActive;
333
- if (defaultProviderId !== undefined)
334
- patch.defaultProviderId = defaultProviderId;
335
- if (defaultModel !== undefined)
336
- patch.defaultModel = defaultModel;
337
385
  if (!attachCredentialId && Object.keys(patch).length === 0) {
338
386
  throw apiError('invalid_gateway_patch', 'At least one routing or gateway field is required.', 400);
339
387
  }
@@ -370,6 +418,7 @@ export function registerTools(inputServer, client, config) {
370
418
  provider: z.string().max(64).optional(),
371
419
  model: z.string().max(200).optional(),
372
420
  status: z.number().int().min(100).max(599).optional(),
421
+ cursor: z.string().max(2048).optional(),
373
422
  limit: z.number().int().min(1).max(200).optional(),
374
423
  offset: z.number().int().min(0).optional(),
375
424
  },
@@ -384,6 +433,7 @@ export function registerTools(inputServer, client, config) {
384
433
  model: z.string().max(200).optional(),
385
434
  status: z.number().int().min(100).max(599).optional(),
386
435
  gatewayId: z.string().uuid().optional(),
436
+ cursor: z.string().max(2048).optional(),
387
437
  limit: z.number().int().min(1).max(200).optional(),
388
438
  offset: z.number().int().min(0).optional(),
389
439
  },
@@ -422,8 +472,8 @@ export function registerTools(inputServer, client, config) {
422
472
  'AIRCTRL_MCP_KEY_*, e.g. AIRCTRL_MCP_KEY_ANTHROPIC_PROD). Given a projectId, a provider slug (from ' +
423
473
  'list_providers: openai/anthropic/gemini) and apiKeyEnv, this: (1) reads the key from that env var and stores ' +
424
474
  'it encrypted (BYOK, validated against the provider) — reusing an existing credential with the same variable ' +
425
- 'name instead of duplicating, (2) verifies defaultModel against that key\'s live catalog and creates a gateway ' +
426
- 'with the exact key/model binding as its default route, (3) mints a gateway ' +
475
+ 'name instead of duplicating, (2) verifies every requested model against that key\'s live catalog and creates a gateway ' +
476
+ 'with all exact key/model bindings, (3) mints a gateway ' +
427
477
  'connection token, and (4) returns the copy-paste connection config. Prefer this over chaining create_gateway ' +
428
478
  '+ add_provider_key + set_routing + create_gateway_token. The gateway token is returned ONCE; the provider key ' +
429
479
  'is never returned.',
@@ -432,12 +482,12 @@ export function registerTools(inputServer, client, config) {
432
482
  provider: z.string().min(1),
433
483
  apiKeyEnv: z.string().min(1),
434
484
  name: z.string().min(1).max(100).optional(),
435
- defaultModel: z.string().min(1).max(200),
485
+ models: z.array(z.string().min(1).max(200)).min(1),
436
486
  tokenName: z.string().min(1).max(64).optional(),
437
487
  baseUrlOverride: z.string().optional(),
438
488
  },
439
489
  }, (args) => run(async () => {
440
- const { projectId, provider, apiKeyEnv, defaultModel, baseUrlOverride } = args;
490
+ const { projectId, provider, apiKeyEnv, models, baseUrlOverride } = args;
441
491
  // 1. Resolve the key value from the named env var (allowlisted prefix).
442
492
  const keyValue = resolveProviderKeyEnv(apiKeyEnv);
443
493
  // 2. Resolve the account from the project (also verifies membership).
@@ -475,16 +525,14 @@ export function registerTools(inputServer, client, config) {
475
525
  });
476
526
  credentialId = credential.credential_id;
477
527
  }
478
- // 5. Create the gateway with one explicit key/model binding and use it as the default route.
528
+ // 5. Create the gateway with every exact key/model binding.
479
529
  let gateway;
480
530
  try {
481
531
  gateway = await client.createGateway({
482
532
  accountId: project.account_id,
483
533
  projectId,
484
534
  name,
485
- defaultProviderId: prov.provider_id,
486
- defaultModel,
487
- credentialBindings: [{ credentialId, modelId: defaultModel }],
535
+ credentialBindings: models.map((modelId) => ({ credentialId, modelId })),
488
536
  });
489
537
  }
490
538
  catch (e) {
@@ -555,7 +603,7 @@ export function registerTools(inputServer, client, config) {
555
603
  }, ({ accountId, gatewayId, tokenId }) => run(() => client.deleteGatewayToken(gatewayId, tokenId, { accountId })));
556
604
  server.registerTool('set_gateway_settings', {
557
605
  title: 'Set gateway settings',
558
- description: 'Update gateway spend, rate, logging, guardrail, cache, and model settings.',
606
+ description: 'Update gateway spend, rate, logging, guardrail, and model settings.',
559
607
  inputSchema: {
560
608
  accountId: z.string().uuid(),
561
609
  gatewayId: z.string().uuid(),
@@ -565,8 +613,6 @@ export function registerTools(inputServer, client, config) {
565
613
  loggingEnabled: z.boolean().optional(),
566
614
  logBodies: z.boolean().optional(),
567
615
  guardrailMode: z.enum(['off', 'flag', 'redact', 'block']).optional(),
568
- cacheEnabled: z.boolean().optional(),
569
- cacheTtlSeconds: z.number().int().min(60).optional(),
570
616
  allowedModels: z.array(z.string().max(200)).optional(),
571
617
  },
572
618
  }, ({ accountId, gatewayId, ...settings }) => run(() => client.updateGatewaySettings(gatewayId, settings, { accountId })));
@@ -585,6 +631,7 @@ export function registerTools(inputServer, client, config) {
585
631
  endpoint: z.string().nullable().optional(),
586
632
  exportMetrics: z.boolean().optional(),
587
633
  exportTraces: z.boolean().optional(),
634
+ exportBodies: z.boolean().optional(),
588
635
  headersEnv: z.string().optional(),
589
636
  clearHeaders: z.boolean().optional(),
590
637
  },
@@ -601,13 +648,16 @@ export function registerTools(inputServer, client, config) {
601
648
  }));
602
649
  server.registerTool('detach_gateway_credential', {
603
650
  title: 'Detach gateway credential',
604
- description: 'Detach a provider credential from a gateway.',
651
+ description: 'Detach one exact model when modelId is provided; otherwise detach the entire provider credential from the gateway.',
605
652
  inputSchema: {
606
653
  accountId: z.string().uuid(),
607
654
  gatewayId: z.string().uuid(),
608
655
  credentialId: z.string().uuid(),
656
+ modelId: z.string().min(1).max(200).optional(),
609
657
  },
610
- }, ({ accountId, gatewayId, credentialId }) => run(() => client.detachGatewayCredential(gatewayId, credentialId, { accountId })));
658
+ }, ({ accountId, gatewayId, credentialId, modelId }) => run(() => modelId
659
+ ? client.detachGatewayCredentialModel(gatewayId, credentialId, modelId, { accountId })
660
+ : client.detachGatewayCredential(gatewayId, credentialId, { accountId })));
611
661
  server.registerTool('read_gateway_log', {
612
662
  title: 'Read gateway log detail',
613
663
  description: 'Read stored request and response bodies for one gateway log when authorized.',
@@ -620,10 +670,11 @@ export function registerTools(inputServer, client, config) {
620
670
  gatewayId: z.string().uuid(),
621
671
  outcome: z.enum(['granted', 'denied', 'error']).optional(),
622
672
  since: z.string().optional(),
673
+ cursor: z.string().max(4096).optional(),
623
674
  limit: z.number().int().min(1).max(200).optional(),
624
675
  offset: z.number().int().min(0).optional(),
625
676
  },
626
- }, ({ gatewayId, outcome, since, limit, offset }) => run(() => client.listGatewayKeyAccess(gatewayId, { outcome, since, limit, offset })));
677
+ }, ({ gatewayId, outcome, since, cursor, limit, offset }) => run(() => client.listGatewayKeyAccess(gatewayId, { outcome, since, cursor, limit, offset })));
627
678
  server.registerTool('list_provider_credentials', {
628
679
  title: 'List provider credentials',
629
680
  description: 'List provider credential metadata for an account. Secret values are never returned.',
@@ -676,6 +727,20 @@ export function registerTools(inputServer, client, config) {
676
727
  limit: z.number().int().min(1).max(1000).optional(),
677
728
  },
678
729
  }, ({ recordId, limit }) => run(() => client.getRecordAudit(recordId, limit)));
730
+ server.registerTool('list_record_audit', {
731
+ title: 'List record audit events',
732
+ description: 'List one stable cursor page of audit-event metadata for a record. Secret values are never returned.',
733
+ inputSchema: {
734
+ recordId: z.string().uuid(),
735
+ limit: z.number().int().min(1).max(100).optional(),
736
+ offset: z.number().int().min(0).optional(),
737
+ cursor: z.string().max(4096).optional(),
738
+ action: z.string().max(160).optional(),
739
+ actor: z.string().max(254).optional(),
740
+ from: z.string().optional(),
741
+ to: z.string().optional(),
742
+ },
743
+ }, ({ recordId, ...input }) => run(() => client.listRecordAudit(recordId, input)));
679
744
  server.registerTool('update_record_metadata', {
680
745
  title: 'Update record metadata',
681
746
  description: 'Update a record name, tags, due date, or rotation interval without changing ciphertext.',
@@ -683,14 +748,15 @@ export function registerTools(inputServer, client, config) {
683
748
  recordId: z.string().uuid(),
684
749
  name: z.string().min(1).optional(),
685
750
  tags: z.array(z.string()).optional(),
751
+ environment: recordEnvironment.optional(),
686
752
  secretDueAt: z.string().nullable().optional(),
687
753
  rotationIntervalDays: z.number().int().min(1).nullable().optional(),
688
754
  },
689
- }, ({ recordId, ...patch }) => {
755
+ }, ({ recordId, environment, ...patch }) => {
690
756
  if (Object.values(patch).every((value) => value === undefined)) {
691
757
  return Promise.resolve(fail(apiError('invalid_record_metadata_patch', 'At least one metadata field is required.', 400)));
692
758
  }
693
- return run(() => client.updateRecordMetadata(recordId, patch));
759
+ return run(() => client.updateRecordMetadata(recordId, { ...patch, ...(environment ? { environment } : {}) }));
694
760
  });
695
761
  server.registerTool('set_record_archive', {
696
762
  title: 'Archive or restore record',
@@ -706,14 +772,16 @@ export function registerTools(inputServer, client, config) {
706
772
  title: 'Rollback record',
707
773
  description: 'Create a new record version from a prior immutable version.',
708
774
  inputSchema: { recordId: z.string().uuid(), targetVersionId: z.string().uuid() },
709
- }, ({ recordId, targetVersionId }) => run(() => client.rollbackRecordToVersion(recordId, targetVersionId)));
775
+ }, ({ recordId, targetVersionId }) => run(() => client.rollbackRecordToVersion(recordId, targetVersionId, recordUnlockPassword(config))));
710
776
  server.registerTool('get_secret', {
711
777
  title: 'Get a secret (decrypted)',
712
778
  description: 'Fetch and decrypt a record locally. Humans use AIRCTRL_MCP_VAULT_PASSWORD; Service Accounts use their ' +
713
779
  'configured credential bundle. Never pass either through the prompt. This puts the secret into the agent ' +
714
- "context — use only when the agent needs the value; for zero model-exposure, route the model call through the gateway instead.",
715
- inputSchema: { recordId: z.string().uuid() },
716
- }, ({ recordId }) => run(() => client.getSecret({ recordId, vaultPassword: recordUnlockPassword(config), audit: true })));
780
+ 'context — use only when the agent needs the value; for zero model-exposure, route the model call through the gateway instead. ' +
781
+ 'Omit environment for General or select development, staging, or production.',
782
+ inputSchema: { recordId: z.string().uuid(), environment: recordEnvironment.optional() },
783
+ }, ({ recordId, environment }) => run(() => client.getSecret({ recordId, vaultPassword: recordUnlockPassword(config), audit: true,
784
+ ...(environment ? { environment } : {}) })));
717
785
  // G5·L4 — thin adapter over the SDK's scoped read (`AirctrlClient.readRecord`). No logic of its own:
718
786
  // the tool params pass straight through to L2.
719
787
  server.registerTool('read_record', {
@@ -725,7 +793,7 @@ export function registerTools(inputServer, client, config) {
725
793
  inputSchema: {
726
794
  recordId: z.string().uuid(),
727
795
  scope: z.array(z.enum(['fields', 'meta', 'owner', 'access', 'full'])).optional(),
728
- environment: z.string().optional(),
796
+ environment: recordEnvironment.optional(),
729
797
  },
730
798
  }, ({ recordId, scope, environment }) => run(() => client.readRecord({
731
799
  recordId,
@@ -762,8 +830,9 @@ export function registerTools(inputServer, client, config) {
762
830
  secretDueAt: z.string().nullable().optional(),
763
831
  rotationIntervalDays: z.number().int().min(1).nullable().optional(),
764
832
  idempotencyKey: z.string().min(1).optional(),
833
+ environment: recordEnvironment.optional(),
765
834
  },
766
- }, ({ projectId, name, secretFormat, fields, generate: gen, options, tags, secretDueAt, rotationIntervalDays, idempotencyKey, }) => run(async () => {
835
+ }, ({ projectId, name, secretFormat, fields, generate: gen, options, tags, secretDueAt, rotationIntervalDays, idempotencyKey, environment, }) => run(async () => {
767
836
  if (!isSecretFormat(secretFormat)) {
768
837
  throw apiError('bad_format', `Unknown secret format '${secretFormat}'.`, 400);
769
838
  }
@@ -772,30 +841,18 @@ export function registerTools(inputServer, client, config) {
772
841
  if (!canGenerate(secretFormat)) {
773
842
  throw apiError('not_generatable', `'${secretFormat}' can't be generated — pass explicit fields instead.`, 400);
774
843
  }
775
- return client.createGeneratedRecord({
776
- projectId,
777
- name,
778
- secretFormat: secretFormat,
779
- options: options ?? {},
780
- extraFields: fields ?? {},
781
- tags,
782
- secretDueAt,
783
- rotationIntervalDays,
784
- idempotencyKey,
785
- vaultPassword,
786
- });
844
+ const common = { projectId, name, secretFormat: secretFormat,
845
+ tags, idempotencyKey, vaultPassword };
846
+ return client.createGeneratedRecord(environment
847
+ ? { ...common, accessScope: 'environment', environmentValues: [{ environment,
848
+ options: options ?? {}, extraFields: fields ?? {}, secretDueAt, rotationIntervalDays }] }
849
+ : { ...common, options: options ?? {}, extraFields: fields ?? {}, secretDueAt, rotationIntervalDays });
787
850
  }
788
- return client.createSecret({
789
- projectId,
790
- name,
791
- secretFormat,
792
- fieldValues: fields ?? {},
793
- tags,
794
- secretDueAt,
795
- rotationIntervalDays,
796
- idempotencyKey,
797
- vaultPassword,
798
- });
851
+ const common = { projectId, name, secretFormat, tags, idempotencyKey, vaultPassword };
852
+ return client.createSecret(environment
853
+ ? { ...common, accessScope: 'environment', environmentValues: [{ environment,
854
+ fieldValues: fields ?? {}, secretDueAt, rotationIntervalDays }] }
855
+ : { ...common, fieldValues: fields ?? {}, secretDueAt, rotationIntervalDays });
799
856
  }));
800
857
  server.registerTool('list_record_anomalies', {
801
858
  title: 'List record anomalies',
@@ -823,7 +880,8 @@ export function registerTools(inputServer, client, config) {
823
880
  accountId: z.string().uuid().optional(),
824
881
  scopeType: z.enum(['user', 'project']).optional(),
825
882
  scopeId: z.string().uuid().optional(),
826
- limit: z.number().int().min(1).max(200).optional(),
883
+ cursor: z.string().max(4096).optional(),
884
+ limit: z.number().int().min(1).max(100).optional(),
827
885
  offset: z.number().int().min(0).optional(),
828
886
  },
829
887
  }, (input) => run(() => client.listRecordAlerts(input)));
@@ -834,7 +892,8 @@ export function registerTools(inputServer, client, config) {
834
892
  accountId: z.string().uuid().optional(),
835
893
  scopeType: z.enum(['user', 'project']).optional(),
836
894
  scopeId: z.string().uuid().optional(),
837
- limit: z.number().int().min(1).max(200).optional(),
895
+ cursor: z.string().max(4096).optional(),
896
+ limit: z.number().int().min(1).max(100).optional(),
838
897
  offset: z.number().int().min(0).optional(),
839
898
  actions: z.array(z.string().min(1)).optional(),
840
899
  },
@@ -848,13 +907,14 @@ export function registerTools(inputServer, client, config) {
848
907
  name: z.string().min(1).max(200).optional(),
849
908
  secretFormat: z.string().optional(),
850
909
  fields: z.record(z.string(), z.unknown()),
910
+ environment: recordEnvironment.optional(),
851
911
  changedFields: z.array(z.string()).optional(),
852
912
  tags: z.array(z.string()).optional(),
853
913
  secretDueAt: z.string().nullable().optional(),
854
914
  rotationIntervalDays: z.number().int().min(1).nullable().optional(),
855
915
  idempotencyKey: z.string().min(1).optional(),
856
916
  },
857
- }, ({ recordId, projectId, name, secretFormat, fields, changedFields, tags, secretDueAt, rotationIntervalDays, idempotencyKey, }) => run(async () => {
917
+ }, ({ recordId, projectId, name, secretFormat, fields, environment, changedFields, tags, secretDueAt, rotationIntervalDays, idempotencyKey, }) => run(async () => {
858
918
  if (secretFormat !== undefined && !isSecretFormat(secretFormat)) {
859
919
  throw apiError('bad_format', `Unknown secret format '${secretFormat}'.`, 400);
860
920
  }
@@ -864,6 +924,7 @@ export function registerTools(inputServer, client, config) {
864
924
  name,
865
925
  secretFormat,
866
926
  fieldValues: fields,
927
+ ...(environment ? { environment } : {}),
867
928
  changedFields,
868
929
  tags,
869
930
  secretDueAt,
@@ -949,7 +1010,9 @@ export function registerTools(inputServer, client, config) {
949
1010
  server.registerTool('get_all', {
950
1011
  title: 'Get all project secrets (decrypted)',
951
1012
  description: 'Decrypt every record in a project that the caller can access, returning name+value pairs (e.g. to inject as env ' +
952
- 'vars). Unlock material comes from the configured human password or Service Account credential, never the prompt. Same model-exposure caveat as get_secret.',
953
- inputSchema: { projectId: z.string().uuid() },
954
- }, ({ projectId }) => run(() => client.getAll({ projectId, vaultPassword: recordUnlockPassword(config), audit: false })));
1013
+ 'vars). Omit environment for General or select development, staging, or production. Unlock material comes from ' +
1014
+ 'the configured human password or Service Account credential, never the prompt. Same model-exposure caveat as get_secret.',
1015
+ inputSchema: { projectId: z.string().uuid(), environment: recordEnvironment.optional() },
1016
+ }, ({ projectId, environment }) => run(() => client.getAll({ projectId, vaultPassword: recordUnlockPassword(config), audit: false,
1017
+ ...(environment ? { environment } : {}) })));
955
1018
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@airctrl/mcp",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "type": "module",
5
5
  "description": "Local/self-hosted MCP server for AIRCTRL records, projects, gateways and usage workflows.",
6
6
  "license": "UNLICENSED",
@@ -37,9 +37,9 @@
37
37
  "start": "node dist/index.js"
38
38
  },
39
39
  "dependencies": {
40
- "@airctrl/sdk": "0.2.0",
41
- "@modelcontextprotocol/sdk": "1.30.0",
42
- "zod": "4.4.3"
40
+ "@airctrl/sdk": "0.4.0",
41
+ "@modelcontextprotocol/sdk": "1.32.1",
42
+ "zod": "4.6.7"
43
43
  },
44
44
  "devDependencies": {
45
45
  "@types/node": "22.20.0"