@airctrl/mcp 0.4.0 → 0.6.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
@@ -16,36 +16,27 @@ Requires Node.js 22.x.
16
16
 
17
17
  ## Current release
18
18
 
19
- **Coordinated package version:** `0.4.0`
19
+ **Coordinated package version:** `0.6.0`
20
20
 
21
21
  ### SDK
22
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.
23
+ - Added the canonical typed MCP Gateway client for gateway, catalog, server, tool, client-key, policy-as-code and call-evidence operations.
24
+ - Added progressive/eager tool-discovery configuration and connector-backed `stdio` catalog server inputs.
30
25
 
31
26
  ### CLI
32
27
 
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.
28
+ - Added the `airctrl mcp-gateway` command family as a thin binding over the SDK.
29
+ - Added `--discovery-mode` runtime configuration and `--connector` for local catalog servers.
36
30
 
37
31
  ### MCP
38
32
 
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.
33
+ - Added MCP Gateway discovery, provisioning, policy-preview and scoped client-key tools backed by the same SDK owner.
34
+ - Added progressive discovery controls; gateway clients can search ranked schemas before invoking one selected tool.
42
35
 
43
36
  ### Release engineering
44
37
 
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.
38
+ - Coordinated SDK, CLI, MCP, Web, and Authenticator package references at `0.6.0`.
39
+ - Added production-image, tarball, installed-consumer, generated README, and public-contract verification for the MCP Gateway release.
49
40
 
50
41
  ## MCP setup
51
42
 
@@ -94,6 +85,49 @@ AIRCTRL_MCP_SA_SERVICE_ACCOUNT_ID = bundle.serviceAccountId # optional
94
85
 
95
86
  Do not set `AIRCTRL_MCP_VAULT_PASSWORD` for a Service Account. MCP rejects partial bundles and mixed human/Service Account unlock material before connecting.
96
87
 
88
+ ### Run a private server connector
89
+
90
+ The default `npx @airctrl/mcp` command exposes AIRCTRL tools to an MCP-compatible AI client. The
91
+ `connector` subcommand has a different purpose: it lets an AIRCTRL MCP Gateway reach approved
92
+ `stdio` servers that run inside your machine or private network.
93
+
94
+ Create a connector from **MCP Gateways → Connectors**. AIRCTRL shows its token and complete
95
+ environment block once. Save them before closing the dialog.
96
+
97
+ | Variable | Required | Purpose |
98
+ |---|---:|---|
99
+ | `AIRCTRL_MCP_CONNECTOR_ID` | Yes | Identifies the project connector created in AIRCTRL. |
100
+ | `AIRCTRL_MCP_CONNECTOR_URL` | Yes | Outbound WebSocket channel. Production connections require `wss:`. |
101
+ | `AIRCTRL_MCP_CONNECTOR_TOKEN` | Yes | One-time connector credential. Keep it outside source control. |
102
+ | `AIRCTRL_MCP_CONNECTOR_SERVERS_FILE` | Yes | Absolute or working-directory-relative path to the local server allowlist. |
103
+
104
+ The servers file defines commands that the connector is allowed to start. Its `env` entries contain
105
+ environment variable names, never credential values:
106
+
107
+ ```json
108
+ {
109
+ "servers": [
110
+ {
111
+ "ref": "internal-tools",
112
+ "command": "path-to-mcp-server",
113
+ "args": [],
114
+ "env": ["MCP_SERVER_API_KEY"]
115
+ }
116
+ ]
117
+ }
118
+ ```
119
+
120
+ Start the outbound connector beside those private servers:
121
+
122
+ ```sh
123
+ npx -y @airctrl/mcp connector
124
+ ```
125
+
126
+ The connector opens the connection to AIRCTRL; it does not require an inbound firewall rule. AIRCTRL
127
+ can request only a `ref` declared in the local file. Command arguments, environment values, tool inputs
128
+ and tool results are not written to connector logs. Revoking the connector in the app closes the channel
129
+ and prevents reconnection.
130
+
97
131
  ### Choose your MCP client
98
132
 
99
133
  AIRCTRL runs as a local `stdio` MCP server. Choose the guide for the AI client you use:
@@ -222,6 +256,19 @@ require API authorization. A Service Account sees only the tools that its API id
222
256
  | `read_usage` | List request metadata for one accessible gateway. |
223
257
  | `read_gateway_log` | Read one accessible gateway log. |
224
258
  | `read_gateway_key_access` | Read provider-key access events for one accessible gateway. |
259
+ | `list_mcp_gateways` | List accessible MCP gateways in a project. |
260
+ | `get_mcp_gateway` | Read one accessible MCP gateway. |
261
+ | `list_mcp_server_catalog` | List curated MCP server recipes. |
262
+ | `list_mcp_servers` | List connected servers. |
263
+ | `get_mcp_server_health` | Read server and connector health. |
264
+ | `list_mcp_tools` | List synchronized tools. |
265
+ | `list_mcp_clients` | List client identities. |
266
+ | `list_mcp_client_keys` | List safe client-key metadata. |
267
+ | `list_mcp_policies` | List tool policies. |
268
+ | `list_mcp_grants` | List principal grants. |
269
+ | `list_mcp_calls` | List bounded call evidence. |
270
+ | `get_mcp_call_metrics` | Read call totals and latency. |
271
+ | `export_mcp_calls_csv` | Export bounded call metadata. |
225
272
 
226
273
  All other tools are human-only and are not registered in Service Account mode. RBAC can still deny
227
274
  any listed operation when the Service Account lacks the required custom-role permission or project access.
@@ -329,19 +376,68 @@ Return pagination.next_cursor without decoding it.
329
376
  | `list_providers` | None | List enabled AI providers. |
330
377
  | `list_provider_credentials` | `accountId` | List safe provider credential metadata. |
331
378
  | `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`. |
332
- | `list_provider_models` | `accountId`, `credentialId` | List models available through a provider credential. |
379
+ | `list_provider_models` | `accountId`, `credentialId` | List models available through a provider credential, including official numeric rates, `displayText`, and context-tiered `rateCard` data. |
333
380
  | `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. |
334
381
  | `rename_provider_credential` | `accountId`, `credentialId`, `label` | Change a provider credential label. |
335
382
  | `revoke_provider_credential` | `accountId`, `credentialId` | Revoke a provider credential. |
336
383
  | `list_gateways` | `projectId` | List gateways in one project. |
337
384
  | `create_gateway` | `accountId`, `projectId`, `name`; optional `slug`, `credentialBindings` | Create a gateway, optionally with explicit credential/model bindings. |
338
385
  | `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. |
386
+ | `get_connection_config` | `gatewayId` | Return compatibility and native OpenAI, Anthropic, Gemini, Mistral, OpenRouter, HiTheo, Groq, Novita AI, Atlas Cloud, and xAI URLs, plus supported realtime WebSocket URLs. |
340
387
  | `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
388
  | `set_gateway_settings` | `accountId`, `gatewayId`; at least one optional settings field | Update limits, logging, guardrails or allowed models. |
342
389
  | `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. |
343
390
  | `delete_gateway` | `accountId`, `gatewayId` | Disable a gateway and revoke its tokens. |
344
391
 
392
+ ### MCP Gateway control plane
393
+
394
+ The local AIRCTRL MCP server exposes MCP Gateway tools through the same typed SDK owner used by the CLI and Web. Read tools cover gateways, the curated server catalog, connected servers, synchronized tools, clients, policies, grants and call evidence.
395
+
396
+ Human-only write tools create and update gateways, servers, clients, scoped keys and policies. Destructive operations require an explicit `confirm: true`. Policy YAML supports a non-mutating preview and a separate confirmed apply.
397
+
398
+ Client-key plaintext is returned once by `create_mcp_client_key`. It is never included by list tools or call evidence.
399
+
400
+ `update_mcp_runtime` accepts `toolDiscoveryMode: "progressive" | "eager"`. Progressive mode keeps upstream schemas out of the initial `tools/list`; the gateway exposes `airctrl__search_tools` and `airctrl__call_tool` so the model retrieves at most five ranked schemas for each focused task step. Search ranking uses the provider, tool name, description and argument metadata while preserving the client's server scope.
401
+
402
+ `create_mcp_server` accepts `authSecretEnv`, the name of an `AIRCTRL_MCP_KEY_*` variable. It never accepts the hosted access token directly in the prompt. `update_mcp_runtime` changes only server-bounded runtime values.
403
+
404
+ | MCP Gateway tool | Purpose |
405
+ |---|---|
406
+ | `list_mcp_gateways` | List project gateways. |
407
+ | `create_mcp_gateway` | Create a gateway. |
408
+ | `list_mcp_server_catalog` | List curated servers. |
409
+ | `get_mcp_gateway` | Read one gateway. |
410
+ | `update_mcp_gateway` | Update one gateway. |
411
+ | `delete_mcp_gateway` | Delete with confirmation. |
412
+ | `update_mcp_runtime` | Update bounded runtime settings. |
413
+ | `list_mcp_servers` | List connected servers. |
414
+ | `create_mcp_server` | Connect a server. |
415
+ | `list_mcp_tools` | List synchronized tools. |
416
+ | `delete_mcp_server` | Remove with confirmation. |
417
+ | `update_mcp_server` | Update one server. |
418
+ | `sync_mcp_server` | Synchronize tools. |
419
+ | `get_mcp_server_health` | Read server health. |
420
+ | `list_mcp_clients` | List clients. |
421
+ | `create_mcp_client` | Register a client. |
422
+ | `revoke_mcp_client` | Revoke with confirmation. |
423
+ | `update_mcp_client` | Rename a client. |
424
+ | `list_mcp_client_keys` | List safe key metadata. |
425
+ | `create_mcp_client_key` | Return one scoped key once. |
426
+ | `revoke_mcp_client_key` | Revoke with confirmation. |
427
+ | `list_mcp_policies` | List policies. |
428
+ | `create_mcp_policy` | Create a policy. |
429
+ | `delete_mcp_policy` | Delete with confirmation. |
430
+ | `list_mcp_grants` | List grants. |
431
+ | `create_mcp_grant` | Create a grant. |
432
+ | `revoke_mcp_grant` | Revoke with confirmation. |
433
+ | `export_mcp_policy` | Export YAML. |
434
+ | `preview_mcp_policy` | Preview YAML without mutation. |
435
+ | `apply_mcp_policy` | Apply YAML with confirmation. |
436
+ | `list_mcp_calls` | List call evidence. |
437
+ | `get_mcp_call_metrics` | Read metrics. |
438
+ | `get_mcp_call_payload` | Read one retained payload. |
439
+ | `export_mcp_calls_csv` | Export metadata CSV. |
440
+
345
441
  ### Gateway tokens
346
442
 
347
443
  | Tool | Inputs | Purpose |
@@ -356,20 +452,20 @@ Return pagination.next_cursor without decoding it.
356
452
 
357
453
  | Tool | Inputs | Purpose |
358
454
  |---|---|---|
359
- | `read_usage` | `gatewayId`; optional `since`, `provider`, `model`, `status`, `cursor`, `limit`, legacy `offset` | Read filtered request metadata for one gateway. |
455
+ | `read_usage` | `gatewayId`; optional `since`, `until`, `provider`, `model`, `status`, `statusClass`, `search`, `cursor`, `limit`, legacy `offset` | Read filtered request metadata for one gateway and search stored bodies when authorized. |
360
456
  | `read_gateway_log` | `gatewayId`, `logId` | Read stored request and response bodies for one gateway log. |
361
- | `read_gateway_key_access` | `gatewayId`; optional `outcome`, `since`, `limit`, `offset` | List provider credential access outcomes. |
362
- | `list_usage_logs` | `projectId`; optional `since`, `provider`, `model`, `status`, `gatewayId`, `cursor`, `limit`, legacy `offset` | List usage across a project. |
457
+ | `read_gateway_key_access` | `gatewayId`; optional `outcome`, `since`, `until`, `limit`, `offset` | List provider credential access outcomes. |
458
+ | `list_usage_logs` | `projectId`; optional `since`, `until`, `provider`, `model`, `status`, `gatewayId`, `cursor`, `limit`, legacy `offset` | List usage across a project. |
363
459
  | `read_usage_log` | `projectId`, `logId` | Read one project's stored request and response bodies. |
364
- | `read_usage_spend` | `projectId` | Compare spend with effective limits. |
365
- | `read_usage_metrics` | `projectId`; optional `since`, `bucket` | Read request, error, token, latency and spend metrics. |
460
+ | `read_usage_spend` | `projectId`; optional `gatewayId` | Compare spend with effective project or gateway limits. |
461
+ | `read_usage_metrics` | `projectId`; optional `since`, `until`, `bucket`, `gatewayId`, `provider`, `model`, `statusClass`, `search` | Read filterable project or gateway metrics. |
366
462
  | `get_otel_export` | `accountId`, `gatewayId` | Read safe OpenTelemetry export settings. |
367
463
  | `set_otel_export` | `accountId`, `gatewayId`; optional export fields | Update OpenTelemetry export settings. |
368
464
 
369
465
  ### Input rules
370
466
 
371
467
  - IDs are UUID strings. Copy them from AIRCTRL instead of asking an agent to guess them.
372
- - Dates and timestamps use ISO 8601. `day` uses `YYYY-MM-DD`; `since` accepts a complete timestamp.
468
+ - Dates and timestamps use ISO 8601. `day` uses `YYYY-MM-DD`; `since` is inclusive and `until` is exclusive.
373
469
  - `read_record.scope` accepts sections only: `fields`, `meta`, `owner`, `access`, or `full`. It does not select individual field names.
374
470
  - 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.
375
471
  - `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.
@@ -600,1006 +696,856 @@ Do not decrypt record values.
600
696
  ## MCP prompt catalog
601
697
 
602
698
  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.
603
-
604
699
  ### How to use this catalog
605
-
606
700
  1. Ask AIRCTRL to check its configuration when identity mode is uncertain.
607
701
  2. Replace every sample ID with an ID returned by AIRCTRL; do not ask the agent to invent one.
608
702
  3. Keep discovery and mutation as separate steps.
609
703
  4. Require a preview before a write or destructive tool.
610
704
  5. Tell the agent whether plaintext may enter its context.
611
705
  6. Stop on `403` instead of asking the agent to search for broader access.
612
-
613
706
  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.
614
-
615
707
  ### Status and projects
616
-
617
708
  #### Check AIRCTRL configuration
618
709
 
619
-
620
-
621
710
  Use this first when you are unsure which profile MCP loaded.
622
711
 
623
-
624
-
625
712
  ```text
626
713
  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.
627
714
  ```
628
715
 
629
-
630
-
631
716
  **MCP tool used:** `airctrl_status`
632
717
 
633
-
634
-
635
718
  #### List accessible accounts
636
719
 
637
-
638
-
639
720
  This tool requires a human PAT.
640
721
 
641
-
642
-
643
722
  ```text
644
723
  Show me every AIRCTRL account I can access, including each name and ID. Do not change anything.
645
724
  ```
646
725
 
647
-
648
-
649
726
  **MCP tool used:** `list_accounts`
650
727
 
651
-
652
-
653
728
  #### List projects
654
-
655
729
  ```text
656
730
  Show the active projects in account "00000000-0000-4000-8000-000000000001". Include each project name, ID and current state. Leave archived projects out.
657
731
  ```
658
732
 
659
-
660
-
661
733
  **MCP tool used:** `list_projects`
662
734
 
663
-
664
-
665
735
  #### View a project
666
-
667
736
  ```text
668
737
  Show me project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Summarize it without changing anything.
669
738
  ```
670
739
 
671
-
672
-
673
740
  **MCP tool used:** `get_project`
674
741
 
675
-
676
-
677
742
  #### Create a project
678
743
 
679
-
680
-
681
744
  The result includes the new project ID.
682
745
 
683
-
684
-
685
746
  ```text
686
747
  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.
687
748
  ```
688
749
 
689
-
690
-
691
750
  **MCP tool used:** `create_project`
692
751
 
693
-
694
-
695
752
  #### Update a project
696
-
697
753
  ```text
698
754
  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.
699
755
  ```
700
756
 
701
-
702
-
703
757
  **MCP tool used:** `update_project`
704
758
 
705
-
706
-
707
759
  #### Archive or restore a project
708
760
 
709
-
710
-
711
761
  Use `archived: false` to restore it.
712
762
 
713
-
714
-
715
763
  ```text
716
764
  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.
717
765
  ```
718
766
 
719
-
720
-
721
767
  **MCP tool used:** `set_project_archive`
722
768
 
723
-
724
-
725
769
  ### Service Account metadata
726
-
727
770
  #### List Service Accounts
728
-
729
771
  ```text
730
772
  Show me the Service Accounts in account "00000000-0000-4000-8000-000000000001". Return only their names, IDs, providers and states.
731
773
  ```
732
774
 
733
-
734
-
735
775
  **MCP tool used:** `list_service_accounts`
736
776
 
737
-
738
-
739
777
  #### View a Service Account
740
778
 
741
-
742
-
743
779
  Both metadata tools require a human PAT.
744
780
 
745
-
746
-
747
781
  ```text
748
782
  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.
749
783
  ```
750
784
 
751
-
752
-
753
785
  **MCP tool used:** `get_service_account`
754
786
 
755
-
756
-
757
787
  ### Record reading and local generation
758
-
759
788
  #### List record metadata
760
-
761
789
  ```text
762
790
  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.
763
791
  ```
764
792
 
765
-
766
-
767
793
  **MCP tool used:** `list_records`
768
794
 
769
-
770
-
771
795
  #### Read a complete record
772
-
773
796
  ```text
774
797
  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.
775
798
  ```
776
799
 
777
-
778
-
779
800
  **MCP tool used:** `get_secret`
780
801
 
781
-
782
-
783
802
  #### Read the record fields section
784
-
785
803
  ```text
786
804
  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.
787
805
  ```
788
806
 
789
-
790
-
791
807
  **MCP tool used:** `read_record`
792
808
 
793
-
794
-
795
809
  #### Load all project records
796
810
 
797
-
798
-
799
811
  This can expose many records to the agent. Prefer `read_record` when one record is enough.
800
812
 
801
-
802
-
803
813
  ```text
804
814
  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.
805
815
  ```
806
816
 
807
-
808
-
809
817
  **MCP tool used:** `get_all`
810
818
 
811
-
812
-
813
819
  #### View supported record formats
814
820
 
815
-
816
-
817
821
  This helper is local and does not call the API.
818
822
 
819
-
820
-
821
823
  ```text
822
824
  Show me the record formats AIRCTRL supports, their required fields and which ones AIRCTRL can generate. Do not create anything.
823
825
  ```
824
826
 
825
-
826
-
827
827
  **MCP tool used:** `list_secret_types`
828
828
 
829
-
830
-
831
829
  #### Generate a secret locally
832
830
 
833
-
834
-
835
831
  This helper generates values locally and stores nothing.
836
832
 
837
-
838
-
839
833
  ```text
840
834
  Generate a 32-character password locally. Do not store or print its value. Tell me only whether generation succeeded.
841
835
  ```
842
836
 
843
-
844
-
845
837
  **MCP tool used:** `generate_secret`
846
838
 
847
-
848
-
849
839
  #### Create an encrypted record
850
-
851
840
  ```text
852
841
  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.
853
842
  ```
854
843
 
855
-
856
-
857
844
  **MCP tool used:** `create_record`
858
845
 
859
-
860
-
861
846
  #### Replace record fields
862
847
 
863
-
864
-
865
848
  When no `recordId` is used, supply `projectId`, `name` and `secretFormat` to create or update by name.
866
849
 
867
-
868
-
869
850
  ```text
870
851
  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.
871
852
  ```
872
853
 
873
-
874
-
875
854
  **MCP tool used:** `set_secret`
876
855
 
877
-
878
-
879
856
  ### Record lifecycle
880
-
881
857
  #### Update record details
882
-
883
858
  ```text
884
859
  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.
885
860
  ```
886
861
 
887
-
888
-
889
862
  **MCP tool used:** `update_record_metadata`
890
863
 
891
-
892
-
893
864
  #### Archive or restore a record
894
-
895
865
  ```text
896
866
  Archive record "00000000-0000-4000-8000-000000000020". Show me its name and ID, then wait for my confirmation.
897
867
  ```
898
868
 
899
-
900
-
901
869
  **MCP tool used:** `set_record_archive`
902
870
 
903
-
904
-
905
871
  #### Transfer record ownership
906
-
907
872
  ```text
908
873
  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.
909
874
  ```
910
875
 
911
-
912
-
913
876
  **MCP tool used:** `transfer_record_ownership`
914
877
 
915
-
916
-
917
878
  #### View record version history
918
-
919
879
  ```text
920
880
  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.
921
881
  ```
922
882
 
923
-
924
-
925
883
  **MCP tool used:** `list_record_versions`
926
884
 
927
-
928
-
929
885
  #### Restore a previous record version
930
-
931
886
  ```text
932
887
  Restore record "00000000-0000-4000-8000-000000000020" from version "00000000-0000-4000-8000-000000000021". Explain what the rollback creates, then wait for my confirmation.
933
888
  ```
934
889
 
935
-
936
-
937
890
  **MCP tool used:** `rollback_record`
938
891
 
939
-
940
-
941
892
  #### Rotate a record
942
-
943
893
  ```text
944
894
  Rotate record "00000000-0000-4000-8000-000000000020". Confirm its name and explain what will change, without exposing its value, then wait for my confirmation.
945
895
  ```
946
896
 
947
-
948
-
949
897
  **MCP tool used:** `rotate_record`
950
898
 
951
-
952
-
953
899
  ### Record sharing
954
-
955
900
  #### Share a record with a user
956
-
957
901
  ```text
958
902
  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.
959
903
  ```
960
904
 
961
-
962
-
963
905
  **MCP tool used:** `share_record_user`
964
906
 
965
-
966
-
967
907
  #### Share a record with a Service Account
968
-
969
908
  ```text
970
909
  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.
971
910
  ```
972
911
 
973
-
974
-
975
912
  **MCP tool used:** `share_record_service_account`
976
913
 
977
-
978
-
979
914
  #### Share a record with a group
980
-
981
915
  ```text
982
916
  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.
983
917
  ```
984
918
 
985
-
986
-
987
919
  **MCP tool used:** `share_record_group`
988
920
 
989
-
990
-
991
921
  #### Remove a user's record access
992
-
993
922
  ```text
994
923
  Remove user "00000000-0000-4000-8000-000000000050" from record "00000000-0000-4000-8000-000000000020". Explain that access ends immediately, then wait for my confirmation.
995
924
  ```
996
925
 
997
-
998
-
999
926
  **MCP tool used:** `revoke_record_user`
1000
927
 
1001
-
1002
-
1003
928
  #### Remove a Service Account's record access
1004
-
1005
929
  ```text
1006
930
  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.
1007
931
  ```
1008
932
 
1009
-
1010
-
1011
933
  **MCP tool used:** `revoke_record_service_account`
1012
934
 
1013
-
1014
-
1015
935
  #### Remove a group's record access
1016
-
1017
936
  ```text
1018
937
  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.
1019
938
  ```
1020
939
 
1021
-
1022
-
1023
940
  **MCP tool used:** `revoke_record_group`
1024
941
 
1025
-
1026
-
1027
942
  ### Groups
1028
-
1029
943
  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
944
  #### List context groups
1032
-
1033
945
  ```text
1034
946
  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
947
  ```
1036
948
 
1037
-
1038
-
1039
949
  **MCP tool used:** `list_groups`
1040
950
 
1041
-
1042
-
1043
951
  #### Read a record's group grants
1044
-
1045
952
  ```text
1046
953
  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
954
  ```
1048
955
 
1049
-
1050
-
1051
956
  **MCP tool used:** `list_record_group_grants`
1052
957
 
1053
-
1054
-
1055
958
  #### Create a group
1056
-
1057
959
  ```text
1058
960
  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
961
  ```
1060
962
 
1061
-
1062
-
1063
963
  **MCP tool used:** `create_group`
1064
964
 
1065
-
1066
-
1067
965
  #### Rename a group
1068
-
1069
966
  ```text
1070
967
  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
968
  ```
1072
969
 
1073
-
1074
-
1075
970
  **MCP tool used:** `update_group`
1076
971
 
1077
-
1078
-
1079
972
  #### Delete a group
1080
-
1081
973
  ```text
1082
974
  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
975
  ```
1084
976
 
1085
-
1086
-
1087
977
  **MCP tool used:** `delete_group`
1088
978
 
1089
-
1090
-
1091
979
  #### List group members
1092
-
1093
980
  ```text
1094
981
  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
982
  ```
1096
983
 
1097
-
1098
-
1099
984
  **MCP tool used:** `list_group_members`
1100
985
 
1101
-
1102
-
1103
986
  #### Add a group member
1104
-
1105
987
  ```text
1106
988
  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
989
  ```
1108
990
 
1109
-
1110
-
1111
991
  **MCP tool used:** `add_group_member`
1112
992
 
1113
-
1114
-
1115
993
  #### Remove a group member
1116
-
1117
994
  ```text
1118
995
  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
996
  ```
1120
997
 
1121
-
1122
-
1123
998
  **MCP tool used:** `remove_group_member`
1124
999
 
1125
-
1126
-
1127
1000
  #### Grant a project role to a group
1128
-
1129
1001
  ```text
1130
1002
  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
1003
  ```
1132
1004
 
1133
-
1134
-
1135
1005
  **MCP tool used:** `grant_project_group`
1136
1006
 
1137
-
1138
-
1139
1007
  #### Revoke one project role from a group
1140
-
1141
1008
  ```text
1142
1009
  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
1010
  ```
1144
1011
 
1145
-
1146
-
1147
- **MCP tool used:** `revoke_project_group`
1148
-
1149
-
1012
+ **MCP tool used:** `revoke_project_group`
1150
1013
 
1151
1014
  #### Complete pending encrypted access
1152
-
1153
1015
  ```text
1154
1016
  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
1017
  ```
1156
1018
 
1157
-
1158
-
1159
1019
  **MCP tool used:** `reconcile_group_access`
1160
1020
 
1161
-
1162
-
1163
1021
  ### Record audit
1164
-
1165
1022
  #### Review one record's audit history
1166
-
1167
1023
  ```text
1168
1024
  Show the 25 most recent audit events for record "00000000-0000-4000-8000-000000000020". Summarize actions, actors and timestamps without exposing secret fields.
1169
1025
  ```
1170
1026
 
1171
-
1172
-
1173
1027
  **MCP tool used:** `read_record_audit`
1174
1028
 
1175
-
1176
-
1177
1029
  #### Page and filter one record's audit history
1178
-
1179
1030
  ```text
1180
1031
  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
1032
  ```
1182
1033
 
1183
-
1184
-
1185
1034
  **MCP tool used:** `list_record_audit`
1186
1035
 
1187
-
1188
-
1189
1036
  #### Find unusual record activity
1190
-
1191
1037
  ```text
1192
1038
  Show unusual record activity in project "00000000-0000-4000-8000-000000000010" under account "00000000-0000-4000-8000-000000000001". Group the results by severity.
1193
1039
  ```
1194
1040
 
1195
-
1196
-
1197
1041
  **MCP tool used:** `list_record_anomalies`
1198
1042
 
1199
-
1200
-
1201
1043
  #### Review daily record activity
1202
-
1203
1044
  ```text
1204
1045
  Summarize record activity for project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001" on the UTC day "2026-09-10".
1205
1046
  ```
1206
1047
 
1207
-
1208
-
1209
1048
  **MCP tool used:** `list_record_activity`
1210
1049
 
1211
-
1212
-
1213
1050
  #### Review record alerts
1214
-
1215
1051
  ```text
1216
1052
  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.
1217
1053
  ```
1218
1054
 
1219
-
1220
-
1221
1055
  **MCP tool used:** `list_record_alerts`
1222
1056
 
1223
-
1224
-
1225
1057
  #### Review secret access events
1226
-
1227
1058
  ```text
1228
1059
  Show the first 25 secret-access events for records in project "00000000-0000-4000-8000-000000000010" under account "00000000-0000-4000-8000-000000000001".
1229
1060
  ```
1230
1061
 
1231
-
1232
-
1233
1062
  **MCP tool used:** `list_record_access`
1234
1063
 
1235
-
1236
-
1237
1064
  ### Providers and credentials
1238
-
1239
1065
  #### List supported AI providers
1240
-
1241
1066
  ```text
1242
1067
  Show the AI providers AIRCTRL supports, including their names, IDs and available configuration. Do not add any credentials.
1243
1068
  ```
1244
1069
 
1245
-
1246
-
1247
1070
  **MCP tool used:** `list_providers`
1248
1071
 
1249
-
1250
-
1251
1072
  #### List provider credentials
1252
-
1253
1073
  ```text
1254
1074
  Show the provider credentials in account "00000000-0000-4000-8000-000000000001". Return labels, IDs, providers and validation status, but never request secret values.
1255
1075
  ```
1256
1076
 
1257
-
1258
-
1259
1077
  **MCP tool used:** `list_provider_credentials`
1260
1078
 
1261
-
1262
-
1263
1079
  #### Add a provider credential
1264
-
1265
1080
  ```text
1266
1081
  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.
1267
1082
  ```
1268
1083
 
1269
-
1270
-
1271
1084
  **MCP tool used:** `add_provider_key`
1272
1085
 
1273
-
1274
-
1275
1086
  #### List models for a credential
1276
-
1277
1087
  ```text
1278
1088
  Show the model IDs available through provider credential "00000000-0000-4000-8000-000000000071" in account "00000000-0000-4000-8000-000000000001".
1279
1089
  ```
1280
1090
 
1281
-
1282
-
1283
1091
  **MCP tool used:** `list_provider_models`
1284
1092
 
1285
-
1286
-
1287
1093
  #### Replace a provider key
1288
-
1289
1094
  ```text
1290
1095
  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.
1291
1096
  ```
1292
1097
 
1293
-
1294
-
1295
1098
  **MCP tool used:** `rotate_provider_key`
1296
1099
 
1297
-
1298
-
1299
1100
  #### Rename a provider credential
1300
-
1301
1101
  ```text
1302
1102
  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.
1303
1103
  ```
1304
1104
 
1305
-
1306
-
1307
1105
  **MCP tool used:** `rename_provider_credential`
1308
1106
 
1309
-
1310
-
1311
1107
  #### Revoke a provider credential
1312
-
1313
1108
  ```text
1314
1109
  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.
1315
1110
  ```
1316
1111
 
1317
-
1318
-
1319
1112
  **MCP tool used:** `revoke_provider_credential`
1320
1113
 
1321
-
1322
-
1323
1114
  ### Gateway setup and routing
1324
-
1325
1115
  #### List gateways
1326
-
1327
1116
  ```text
1328
1117
  Show the gateways in project "00000000-0000-4000-8000-000000000010", including each name, ID, provider and active state.
1329
1118
  ```
1330
1119
 
1331
-
1332
-
1333
1120
  **MCP tool used:** `list_gateways`
1334
1121
 
1335
-
1336
-
1337
1122
  #### Create a gateway
1338
-
1339
1123
  ```text
1340
1124
  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.
1341
1125
  ```
1342
1126
 
1343
-
1344
-
1345
1127
  **MCP tool used:** `create_gateway`
1346
1128
 
1347
-
1348
-
1349
1129
  #### Set up a complete gateway
1350
1130
 
1351
-
1352
-
1353
1131
  This workflow can add a provider credential, create a gateway and create a one-time gateway token.
1354
1132
 
1355
-
1356
-
1357
1133
  ```text
1358
1134
  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.
1359
1135
  ```
1360
1136
 
1361
-
1362
-
1363
1137
  **MCP tool used:** `setup_gateway`
1364
1138
 
1365
-
1366
-
1367
1139
  #### View gateway connection settings
1368
-
1369
1140
  ```text
1370
1141
  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.
1371
1142
  ```
1372
1143
 
1373
-
1374
-
1375
1144
  **MCP tool used:** `get_connection_config`
1376
1145
 
1377
-
1378
-
1379
1146
  #### Change gateway routing
1380
-
1381
1147
  ```text
1382
1148
  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.
1383
1149
  ```
1384
1150
 
1385
-
1386
-
1387
1151
  **MCP tool used:** `set_routing`
1388
1152
 
1389
-
1390
-
1391
1153
  #### Change gateway limits and behavior
1392
-
1393
1154
  ```text
1394
1155
  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.
1395
1156
  ```
1396
1157
 
1397
-
1398
-
1399
1158
  **MCP tool used:** `set_gateway_settings`
1400
1159
 
1401
-
1402
-
1403
1160
  #### Detach a provider credential
1404
-
1405
1161
  ```text
1406
1162
  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
-
1408
1163
  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.
1409
1164
  ```
1410
1165
 
1411
-
1412
-
1413
1166
  **MCP tool used:** `detach_gateway_credential`
1414
1167
 
1168
+ #### Delete a gateway
1169
+ ```text
1170
+ 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.
1171
+ ```
1415
1172
 
1173
+ **MCP tool used:** `delete_gateway`
1416
1174
 
1417
- #### Delete a gateway
1175
+ ### Gateway tokens
1176
+ #### List gateway tokens
1177
+ ```text
1178
+ Show the tokens for gateway "00000000-0000-4000-8000-000000000030", including IDs, labels, status and expiration. Never request their secret values.
1179
+ ```
1418
1180
 
1181
+ **MCP tool used:** `list_gateway_tokens`
1182
+
1183
+ #### Create a gateway token
1419
1184
  ```text
1420
- 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.
1185
+ 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.
1421
1186
  ```
1422
1187
 
1188
+ **MCP tool used:** `create_gateway_token`
1423
1189
 
1190
+ #### Rename a gateway token
1191
+ ```text
1192
+ 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.
1193
+ ```
1424
1194
 
1425
- **MCP tool used:** `delete_gateway`
1195
+ **MCP tool used:** `rename_gateway_token`
1426
1196
 
1197
+ #### Revoke a gateway token
1198
+ ```text
1199
+ 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.
1200
+ ```
1427
1201
 
1202
+ **MCP tool used:** `revoke_gateway_token`
1428
1203
 
1429
- ### Gateway tokens
1204
+ #### Delete a gateway token
1205
+ ```text
1206
+ 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.
1207
+ ```
1430
1208
 
1431
- #### List gateway tokens
1209
+ **MCP tool used:** `delete_gateway_token`
1432
1210
 
1211
+ ### Logs, usage and OpenTelemetry
1212
+ #### Review gateway requests
1433
1213
  ```text
1434
- Show the tokens for gateway "00000000-0000-4000-8000-000000000030", including IDs, labels, status and expiration. Never request their secret values.
1214
+ 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.
1435
1215
  ```
1436
1216
 
1217
+ **MCP tool used:** `read_usage`
1437
1218
 
1219
+ #### Inspect one gateway request
1220
+ ```text
1221
+ 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.
1222
+ ```
1438
1223
 
1439
- **MCP tool used:** `list_gateway_tokens`
1224
+ **MCP tool used:** `read_gateway_log`
1440
1225
 
1226
+ #### Review provider-key access
1227
+ ```text
1228
+ 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.
1229
+ ```
1441
1230
 
1231
+ **MCP tool used:** `read_gateway_key_access`
1442
1232
 
1443
- #### Create a gateway token
1233
+ #### Review project usage logs
1234
+ ```text
1235
+ 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.
1236
+ ```
1237
+
1238
+ **MCP tool used:** `list_usage_logs`
1444
1239
 
1240
+ #### Inspect one project usage log
1445
1241
  ```text
1446
- 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.
1242
+ 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.
1447
1243
  ```
1448
1244
 
1245
+ **MCP tool used:** `read_usage_log`
1449
1246
 
1247
+ #### Review project spend
1248
+ ```text
1249
+ Compare current spend in project "00000000-0000-4000-8000-000000000010" with its effective limit. Do not change any settings.
1250
+ ```
1450
1251
 
1451
- **MCP tool used:** `create_gateway_token`
1252
+ **MCP tool used:** `read_usage_spend`
1452
1253
 
1254
+ #### Review project usage metrics
1255
+ ```text
1256
+ Summarize daily requests, errors, tokens, latency and spend for project "00000000-0000-4000-8000-000000000010" since "2026-09-01T00:00:00Z".
1257
+ ```
1453
1258
 
1259
+ **MCP tool used:** `read_usage_metrics`
1454
1260
 
1455
- #### Rename a gateway token
1261
+ #### View OpenTelemetry settings
1262
+ ```text
1263
+ 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.
1264
+ ```
1265
+
1266
+ **MCP tool used:** `get_otel_export`
1456
1267
 
1268
+ #### Change OpenTelemetry settings
1457
1269
  ```text
1458
- 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.
1270
+ 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.
1459
1271
  ```
1460
1272
 
1273
+ **MCP tool used:** `set_otel_export`
1461
1274
 
1275
+ ### MCP Gateway prompts
1276
+ #### List project MCP gateways
1277
+ ```text
1278
+ List MCP gateways in project "00000000-0000-4000-8000-000000000010".
1279
+ ```
1462
1280
 
1463
- **MCP tool used:** `rename_gateway_token`
1281
+ **MCP tool used:** `list_mcp_gateways`
1464
1282
 
1465
1283
 
1284
+ #### Create an MCP gateway
1285
+ ```text
1286
+ Create an MCP gateway named "Engineering" in project "00000000-0000-4000-8000-000000000010".
1287
+ ```
1288
+
1289
+ **MCP tool used:** `create_mcp_gateway`
1466
1290
 
1467
- #### Revoke a gateway token
1468
1291
 
1292
+ #### Review the server catalog
1469
1293
  ```text
1470
- 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.
1294
+ Show the curated MCP server catalog and official documentation links.
1471
1295
  ```
1472
1296
 
1297
+ **MCP tool used:** `list_mcp_server_catalog`
1473
1298
 
1474
1299
 
1475
- **MCP tool used:** `revoke_gateway_token`
1300
+ #### Read gateway detail
1301
+ ```text
1302
+ Show safe details for MCP gateway "00000000-0000-4000-8000-000000000020".
1303
+ ```
1476
1304
 
1305
+ **MCP tool used:** `get_mcp_gateway`
1477
1306
 
1478
1307
 
1479
- #### Delete a gateway token
1308
+ #### Rename the gateway
1309
+ ```text
1310
+ Rename MCP gateway "00000000-0000-4000-8000-000000000020" to "Engineering tools".
1311
+ ```
1480
1312
 
1313
+ **MCP tool used:** `update_mcp_gateway`
1314
+
1315
+
1316
+ #### Delete the gateway
1481
1317
  ```text
1482
- 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.
1318
+ Delete MCP gateway "00000000-0000-4000-8000-000000000020". Show the impact and wait for confirmation.
1483
1319
  ```
1484
1320
 
1321
+ **MCP tool used:** `delete_mcp_gateway`
1485
1322
 
1486
1323
 
1487
- **MCP tool used:** `delete_gateway_token`
1324
+ #### Configure runtime limits
1325
+ ```text
1326
+ Set the request timeout to 30 seconds for MCP gateway "00000000-0000-4000-8000-000000000020".
1327
+ ```
1488
1328
 
1329
+ **MCP tool used:** `update_mcp_runtime`
1489
1330
 
1490
1331
 
1491
- ### Logs, usage and OpenTelemetry
1332
+ #### List connected servers
1333
+ ```text
1334
+ List servers connected to MCP gateway "00000000-0000-4000-8000-000000000020".
1335
+ ```
1336
+
1337
+ **MCP tool used:** `list_mcp_servers`
1492
1338
 
1493
- #### Review gateway requests
1494
1339
 
1340
+ #### Connect a catalog server
1495
1341
  ```text
1496
- 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.
1342
+ Connect Linear to MCP gateway "00000000-0000-4000-8000-000000000020" and read its token from environment variable "AIRCTRL_MCP_KEY_LINEAR".
1497
1343
  ```
1498
1344
 
1345
+ **MCP tool used:** `create_mcp_server`
1499
1346
 
1500
1347
 
1501
- **MCP tool used:** `read_usage`
1348
+ #### List synchronized tools
1349
+ ```text
1350
+ List synchronized tools for MCP gateway "00000000-0000-4000-8000-000000000020".
1351
+ ```
1502
1352
 
1353
+ **MCP tool used:** `list_mcp_tools`
1503
1354
 
1504
1355
 
1505
- #### Inspect one gateway request
1356
+ #### Remove a server
1357
+ ```text
1358
+ Remove server "00000000-0000-4000-8000-000000000030" from its MCP gateway. Show the impact and wait for confirmation.
1359
+ ```
1506
1360
 
1361
+ **MCP tool used:** `delete_mcp_server`
1362
+
1363
+
1364
+ #### Update a server
1507
1365
  ```text
1508
- 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.
1366
+ Enable server "00000000-0000-4000-8000-000000000030" on MCP gateway "00000000-0000-4000-8000-000000000020".
1509
1367
  ```
1510
1368
 
1369
+ **MCP tool used:** `update_mcp_server`
1511
1370
 
1512
1371
 
1513
- **MCP tool used:** `read_gateway_log`
1372
+ #### Synchronize a server
1373
+ ```text
1374
+ Synchronize the tool inventory for server "00000000-0000-4000-8000-000000000030".
1375
+ ```
1514
1376
 
1377
+ **MCP tool used:** `sync_mcp_server`
1515
1378
 
1516
1379
 
1517
- #### Review provider-key access
1380
+ #### Check server health
1381
+ ```text
1382
+ Show health and connector state for server "00000000-0000-4000-8000-000000000030".
1383
+ ```
1384
+
1385
+ **MCP tool used:** `get_mcp_server_health`
1518
1386
 
1387
+
1388
+ #### List clients
1519
1389
  ```text
1520
- 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.
1390
+ List clients registered to MCP gateway "00000000-0000-4000-8000-000000000020".
1521
1391
  ```
1522
1392
 
1393
+ **MCP tool used:** `list_mcp_clients`
1523
1394
 
1524
1395
 
1525
- **MCP tool used:** `read_gateway_key_access`
1396
+ #### Register a client
1397
+ ```text
1398
+ Register a client named "Cursor" on MCP gateway "00000000-0000-4000-8000-000000000020".
1399
+ ```
1526
1400
 
1401
+ **MCP tool used:** `create_mcp_client`
1527
1402
 
1528
1403
 
1529
- #### Review project usage logs
1404
+ #### Revoke a client
1405
+ ```text
1406
+ Revoke client "00000000-0000-4000-8000-000000000040" and its keys. Show the impact and wait for confirmation.
1407
+ ```
1408
+
1409
+ **MCP tool used:** `revoke_mcp_client`
1530
1410
 
1411
+
1412
+ #### Rename a client
1531
1413
  ```text
1532
- 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.
1414
+ Rename client "00000000-0000-4000-8000-000000000040" to "Cursor CI".
1533
1415
  ```
1534
1416
 
1417
+ **MCP tool used:** `update_mcp_client`
1535
1418
 
1536
1419
 
1537
- **MCP tool used:** `list_usage_logs`
1420
+ #### List client keys
1421
+ ```text
1422
+ List safe key metadata for client "00000000-0000-4000-8000-000000000040".
1423
+ ```
1538
1424
 
1425
+ **MCP tool used:** `list_mcp_client_keys`
1539
1426
 
1540
1427
 
1541
- #### Inspect one project usage log
1428
+ #### Create a scoped key
1429
+ ```text
1430
+ Create a connect-and-call key for client "00000000-0000-4000-8000-000000000040" and show it once.
1431
+ ```
1432
+
1433
+ **MCP tool used:** `create_mcp_client_key`
1434
+
1542
1435
 
1436
+ #### Revoke a client key
1543
1437
  ```text
1544
- 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.
1438
+ Revoke client key "00000000-0000-4000-8000-000000000050". Wait for confirmation.
1545
1439
  ```
1546
1440
 
1441
+ **MCP tool used:** `revoke_mcp_client_key`
1547
1442
 
1548
1443
 
1549
- **MCP tool used:** `read_usage_log`
1444
+ #### List tool policies
1445
+ ```text
1446
+ List policies on MCP gateway "00000000-0000-4000-8000-000000000020".
1447
+ ```
1550
1448
 
1449
+ **MCP tool used:** `list_mcp_policies`
1551
1450
 
1552
1451
 
1553
- #### Review project spend
1452
+ #### Create a read-only policy
1453
+ ```text
1454
+ Create a read-only allow policy for every tool on MCP gateway "00000000-0000-4000-8000-000000000020".
1455
+ ```
1456
+
1457
+ **MCP tool used:** `create_mcp_policy`
1458
+
1554
1459
 
1460
+ #### Delete a policy
1555
1461
  ```text
1556
- Compare current spend in project "00000000-0000-4000-8000-000000000010" with its effective limit. Do not change any settings.
1462
+ Delete policy "00000000-0000-4000-8000-000000000060". Wait for confirmation.
1557
1463
  ```
1558
1464
 
1465
+ **MCP tool used:** `delete_mcp_policy`
1559
1466
 
1560
1467
 
1561
- **MCP tool used:** `read_usage_spend`
1468
+ #### List access grants
1469
+ ```text
1470
+ List access grants on MCP gateway "00000000-0000-4000-8000-000000000020".
1471
+ ```
1562
1472
 
1473
+ **MCP tool used:** `list_mcp_grants`
1563
1474
 
1564
1475
 
1565
- #### Review project usage metrics
1476
+ #### Grant group access
1477
+ ```text
1478
+ Give group "00000000-0000-4000-8000-000000000070" read-only access to MCP gateway "00000000-0000-4000-8000-000000000020".
1479
+ ```
1480
+
1481
+ **MCP tool used:** `create_mcp_grant`
1566
1482
 
1483
+
1484
+ #### Revoke a grant
1567
1485
  ```text
1568
- Summarize daily requests, errors, tokens, latency and spend for project "00000000-0000-4000-8000-000000000010" since "2026-09-01T00:00:00Z".
1486
+ Revoke grant "00000000-0000-4000-8000-000000000080". Wait for confirmation.
1569
1487
  ```
1570
1488
 
1489
+ **MCP tool used:** `revoke_mcp_grant`
1571
1490
 
1572
1491
 
1573
- **MCP tool used:** `read_usage_metrics`
1492
+ #### Export policy YAML
1493
+ ```text
1494
+ Export the current policy document for MCP gateway "00000000-0000-4000-8000-000000000020".
1495
+ ```
1574
1496
 
1497
+ **MCP tool used:** `export_mcp_policy`
1575
1498
 
1576
1499
 
1577
- #### View OpenTelemetry settings
1500
+ #### Preview policy YAML
1501
+ ```text
1502
+ Validate this policy document and show its diff without applying it.
1503
+ ```
1504
+
1505
+ **MCP tool used:** `preview_mcp_policy`
1578
1506
 
1507
+
1508
+ #### Apply policy YAML
1579
1509
  ```text
1580
- 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.
1510
+ Apply the reviewed policy document without pruning. Show the diff and wait for confirmation.
1581
1511
  ```
1582
1512
 
1513
+ **MCP tool used:** `apply_mcp_policy`
1583
1514
 
1584
1515
 
1585
- **MCP tool used:** `get_otel_export`
1516
+ #### List call evidence
1517
+ ```text
1518
+ List blocked tool calls for MCP gateway "00000000-0000-4000-8000-000000000020".
1519
+ ```
1586
1520
 
1521
+ **MCP tool used:** `list_mcp_calls`
1587
1522
 
1588
1523
 
1589
- #### Change OpenTelemetry settings
1524
+ #### Read call metrics
1525
+ ```text
1526
+ Show call totals, outcomes and average latency for MCP gateway "00000000-0000-4000-8000-000000000020".
1527
+ ```
1528
+
1529
+ **MCP tool used:** `get_mcp_call_metrics`
1590
1530
 
1531
+
1532
+ #### Read retained payload
1591
1533
  ```text
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.
1534
+ Read the retained payload for call "00000000-0000-4000-8000-000000000090" only if I am authorized.
1593
1535
  ```
1594
1536
 
1537
+ **MCP tool used:** `get_mcp_call_payload`
1595
1538
 
1596
1539
 
1597
- **MCP tool used:** `set_otel_export`
1540
+ #### Export call evidence
1541
+ ```text
1542
+ Export bounded call metadata for MCP gateway "00000000-0000-4000-8000-000000000020" as CSV.
1543
+ ```
1598
1544
 
1545
+ **MCP tool used:** `export_mcp_calls_csv`
1599
1546
 
1600
1547
 
1601
1548
  ### When a prompt fails
1602
-
1603
1549
  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.
1604
1550
  ## MCP workflow prompts
1605
1551