@airctrl/mcp 0.5.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,26 +16,27 @@ Requires Node.js 22.x.
16
16
 
17
17
  ## Current release
18
18
 
19
- **Coordinated package version:** `0.5.0`
19
+ **Coordinated package version:** `0.6.0`
20
20
 
21
21
  ### SDK
22
22
 
23
- - Added privileged full-text gateway log search, HTTP status-family filtering, and gateway-scoped usage metrics and spend inputs.
24
- - Added native connection URLs for Groq, Novita AI, Atlas Cloud, and xAI to the shared gateway connection builder.
25
- - Added pricing display text and structured rate-card tiers so provider-published zero and context-tiered rates remain explicit.
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.
26
25
 
27
26
  ### CLI
28
27
 
29
- - Added gateway log `--search` and `--status-class` filters plus gateway-scoped usage metrics and spend flags.
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.
30
30
 
31
31
  ### MCP
32
32
 
33
- - Added the same gateway log search and scoped metrics inputs to `read_usage`, `read_usage_metrics`, and `read_usage_spend`.
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.
34
35
 
35
36
  ### Release engineering
36
37
 
37
- - Coordinated SDK, CLI, MCP, Web, and Authenticator package references at `0.5.0` so clean builds consume the exact release candidate instead of the previously published SDK.
38
- - Retained sealed-candidate certification and manual npm publication with final approval and 2FA.
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.
39
40
 
40
41
  ## MCP setup
41
42
 
@@ -84,6 +85,49 @@ AIRCTRL_MCP_SA_SERVICE_ACCOUNT_ID = bundle.serviceAccountId # optional
84
85
 
85
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.
86
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
+
87
131
  ### Choose your MCP client
88
132
 
89
133
  AIRCTRL runs as a local `stdio` MCP server. Choose the guide for the AI client you use:
@@ -212,6 +256,19 @@ require API authorization. A Service Account sees only the tools that its API id
212
256
  | `read_usage` | List request metadata for one accessible gateway. |
213
257
  | `read_gateway_log` | Read one accessible gateway log. |
214
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. |
215
272
 
216
273
  All other tools are human-only and are not registered in Service Account mode. RBAC can still deny
217
274
  any listed operation when the Service Account lacks the required custom-role permission or project access.
@@ -332,6 +389,55 @@ Return pagination.next_cursor without decoding it.
332
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. |
333
390
  | `delete_gateway` | `accountId`, `gatewayId` | Disable a gateway and revoke its tokens. |
334
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
+
335
441
  ### Gateway tokens
336
442
 
337
443
  | Tool | Inputs | Purpose |
@@ -346,20 +452,20 @@ Return pagination.next_cursor without decoding it.
346
452
 
347
453
  | Tool | Inputs | Purpose |
348
454
  |---|---|---|
349
- | `read_usage` | `gatewayId`; optional `since`, `provider`, `model`, `status`, `statusClass`, `search`, `cursor`, `limit`, legacy `offset` | Read filtered request metadata for one gateway and search stored bodies when authorized. |
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. |
350
456
  | `read_gateway_log` | `gatewayId`, `logId` | Read stored request and response bodies for one gateway log. |
351
- | `read_gateway_key_access` | `gatewayId`; optional `outcome`, `since`, `limit`, `offset` | List provider credential access outcomes. |
352
- | `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. |
353
459
  | `read_usage_log` | `projectId`, `logId` | Read one project's stored request and response bodies. |
354
460
  | `read_usage_spend` | `projectId`; optional `gatewayId` | Compare spend with effective project or gateway limits. |
355
- | `read_usage_metrics` | `projectId`; optional `since`, `bucket`, `gatewayId`, `provider`, `model`, `statusClass`, `search` | Read filterable project or gateway metrics. |
461
+ | `read_usage_metrics` | `projectId`; optional `since`, `until`, `bucket`, `gatewayId`, `provider`, `model`, `statusClass`, `search` | Read filterable project or gateway metrics. |
356
462
  | `get_otel_export` | `accountId`, `gatewayId` | Read safe OpenTelemetry export settings. |
357
463
  | `set_otel_export` | `accountId`, `gatewayId`; optional export fields | Update OpenTelemetry export settings. |
358
464
 
359
465
  ### Input rules
360
466
 
361
467
  - IDs are UUID strings. Copy them from AIRCTRL instead of asking an agent to guess them.
362
- - 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.
363
469
  - `read_record.scope` accepts sections only: `fields`, `meta`, `owner`, `access`, or `full`. It does not select individual field names.
364
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.
365
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.
@@ -590,1006 +696,856 @@ Do not decrypt record values.
590
696
  ## MCP prompt catalog
591
697
 
592
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.
593
-
594
699
  ### How to use this catalog
595
-
596
700
  1. Ask AIRCTRL to check its configuration when identity mode is uncertain.
597
701
  2. Replace every sample ID with an ID returned by AIRCTRL; do not ask the agent to invent one.
598
702
  3. Keep discovery and mutation as separate steps.
599
703
  4. Require a preview before a write or destructive tool.
600
704
  5. Tell the agent whether plaintext may enter its context.
601
705
  6. Stop on `403` instead of asking the agent to search for broader access.
602
-
603
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.
604
-
605
707
  ### Status and projects
606
-
607
708
  #### Check AIRCTRL configuration
608
709
 
609
-
610
-
611
710
  Use this first when you are unsure which profile MCP loaded.
612
711
 
613
-
614
-
615
712
  ```text
616
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.
617
714
  ```
618
715
 
619
-
620
-
621
716
  **MCP tool used:** `airctrl_status`
622
717
 
623
-
624
-
625
718
  #### List accessible accounts
626
719
 
627
-
628
-
629
720
  This tool requires a human PAT.
630
721
 
631
-
632
-
633
722
  ```text
634
723
  Show me every AIRCTRL account I can access, including each name and ID. Do not change anything.
635
724
  ```
636
725
 
637
-
638
-
639
726
  **MCP tool used:** `list_accounts`
640
727
 
641
-
642
-
643
728
  #### List projects
644
-
645
729
  ```text
646
730
  Show the active projects in account "00000000-0000-4000-8000-000000000001". Include each project name, ID and current state. Leave archived projects out.
647
731
  ```
648
732
 
649
-
650
-
651
733
  **MCP tool used:** `list_projects`
652
734
 
653
-
654
-
655
735
  #### View a project
656
-
657
736
  ```text
658
737
  Show me project "00000000-0000-4000-8000-000000000010" in account "00000000-0000-4000-8000-000000000001". Summarize it without changing anything.
659
738
  ```
660
739
 
661
-
662
-
663
740
  **MCP tool used:** `get_project`
664
741
 
665
-
666
-
667
742
  #### Create a project
668
743
 
669
-
670
-
671
744
  The result includes the new project ID.
672
745
 
673
-
674
-
675
746
  ```text
676
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.
677
748
  ```
678
749
 
679
-
680
-
681
750
  **MCP tool used:** `create_project`
682
751
 
683
-
684
-
685
752
  #### Update a project
686
-
687
753
  ```text
688
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.
689
755
  ```
690
756
 
691
-
692
-
693
757
  **MCP tool used:** `update_project`
694
758
 
695
-
696
-
697
759
  #### Archive or restore a project
698
760
 
699
-
700
-
701
761
  Use `archived: false` to restore it.
702
762
 
703
-
704
-
705
763
  ```text
706
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.
707
765
  ```
708
766
 
709
-
710
-
711
767
  **MCP tool used:** `set_project_archive`
712
768
 
713
-
714
-
715
769
  ### Service Account metadata
716
-
717
770
  #### List Service Accounts
718
-
719
771
  ```text
720
772
  Show me the Service Accounts in account "00000000-0000-4000-8000-000000000001". Return only their names, IDs, providers and states.
721
773
  ```
722
774
 
723
-
724
-
725
775
  **MCP tool used:** `list_service_accounts`
726
776
 
727
-
728
-
729
777
  #### View a Service Account
730
778
 
731
-
732
-
733
779
  Both metadata tools require a human PAT.
734
780
 
735
-
736
-
737
781
  ```text
738
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.
739
783
  ```
740
784
 
741
-
742
-
743
785
  **MCP tool used:** `get_service_account`
744
786
 
745
-
746
-
747
787
  ### Record reading and local generation
748
-
749
788
  #### List record metadata
750
-
751
789
  ```text
752
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.
753
791
  ```
754
792
 
755
-
756
-
757
793
  **MCP tool used:** `list_records`
758
794
 
759
-
760
-
761
795
  #### Read a complete record
762
-
763
796
  ```text
764
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.
765
798
  ```
766
799
 
767
-
768
-
769
800
  **MCP tool used:** `get_secret`
770
801
 
771
-
772
-
773
802
  #### Read the record fields section
774
-
775
803
  ```text
776
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.
777
805
  ```
778
806
 
779
-
780
-
781
807
  **MCP tool used:** `read_record`
782
808
 
783
-
784
-
785
809
  #### Load all project records
786
810
 
787
-
788
-
789
811
  This can expose many records to the agent. Prefer `read_record` when one record is enough.
790
812
 
791
-
792
-
793
813
  ```text
794
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.
795
815
  ```
796
816
 
797
-
798
-
799
817
  **MCP tool used:** `get_all`
800
818
 
801
-
802
-
803
819
  #### View supported record formats
804
820
 
805
-
806
-
807
821
  This helper is local and does not call the API.
808
822
 
809
-
810
-
811
823
  ```text
812
824
  Show me the record formats AIRCTRL supports, their required fields and which ones AIRCTRL can generate. Do not create anything.
813
825
  ```
814
826
 
815
-
816
-
817
827
  **MCP tool used:** `list_secret_types`
818
828
 
819
-
820
-
821
829
  #### Generate a secret locally
822
830
 
823
-
824
-
825
831
  This helper generates values locally and stores nothing.
826
832
 
827
-
828
-
829
833
  ```text
830
834
  Generate a 32-character password locally. Do not store or print its value. Tell me only whether generation succeeded.
831
835
  ```
832
836
 
833
-
834
-
835
837
  **MCP tool used:** `generate_secret`
836
838
 
837
-
838
-
839
839
  #### Create an encrypted record
840
-
841
840
  ```text
842
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.
843
842
  ```
844
843
 
845
-
846
-
847
844
  **MCP tool used:** `create_record`
848
845
 
849
-
850
-
851
846
  #### Replace record fields
852
847
 
853
-
854
-
855
848
  When no `recordId` is used, supply `projectId`, `name` and `secretFormat` to create or update by name.
856
849
 
857
-
858
-
859
850
  ```text
860
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.
861
852
  ```
862
853
 
863
-
864
-
865
854
  **MCP tool used:** `set_secret`
866
855
 
867
-
868
-
869
856
  ### Record lifecycle
870
-
871
857
  #### Update record details
872
-
873
858
  ```text
874
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.
875
860
  ```
876
861
 
877
-
878
-
879
862
  **MCP tool used:** `update_record_metadata`
880
863
 
881
-
882
-
883
864
  #### Archive or restore a record
884
-
885
865
  ```text
886
866
  Archive record "00000000-0000-4000-8000-000000000020". Show me its name and ID, then wait for my confirmation.
887
867
  ```
888
868
 
889
-
890
-
891
869
  **MCP tool used:** `set_record_archive`
892
870
 
893
-
894
-
895
871
  #### Transfer record ownership
896
-
897
872
  ```text
898
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.
899
874
  ```
900
875
 
901
-
902
-
903
876
  **MCP tool used:** `transfer_record_ownership`
904
877
 
905
-
906
-
907
878
  #### View record version history
908
-
909
879
  ```text
910
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.
911
881
  ```
912
882
 
913
-
914
-
915
883
  **MCP tool used:** `list_record_versions`
916
884
 
917
-
918
-
919
885
  #### Restore a previous record version
920
-
921
886
  ```text
922
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.
923
888
  ```
924
889
 
925
-
926
-
927
890
  **MCP tool used:** `rollback_record`
928
891
 
929
-
930
-
931
892
  #### Rotate a record
932
-
933
893
  ```text
934
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.
935
895
  ```
936
896
 
937
-
938
-
939
897
  **MCP tool used:** `rotate_record`
940
898
 
941
-
942
-
943
899
  ### Record sharing
944
-
945
900
  #### Share a record with a user
946
-
947
901
  ```text
948
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.
949
903
  ```
950
904
 
951
-
952
-
953
905
  **MCP tool used:** `share_record_user`
954
906
 
955
-
956
-
957
907
  #### Share a record with a Service Account
958
-
959
908
  ```text
960
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.
961
910
  ```
962
911
 
963
-
964
-
965
912
  **MCP tool used:** `share_record_service_account`
966
913
 
967
-
968
-
969
914
  #### Share a record with a group
970
-
971
915
  ```text
972
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.
973
917
  ```
974
918
 
975
-
976
-
977
919
  **MCP tool used:** `share_record_group`
978
920
 
979
-
980
-
981
921
  #### Remove a user's record access
982
-
983
922
  ```text
984
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.
985
924
  ```
986
925
 
987
-
988
-
989
926
  **MCP tool used:** `revoke_record_user`
990
927
 
991
-
992
-
993
928
  #### Remove a Service Account's record access
994
-
995
929
  ```text
996
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.
997
931
  ```
998
932
 
999
-
1000
-
1001
933
  **MCP tool used:** `revoke_record_service_account`
1002
934
 
1003
-
1004
-
1005
935
  #### Remove a group's record access
1006
-
1007
936
  ```text
1008
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.
1009
938
  ```
1010
939
 
1011
-
1012
-
1013
940
  **MCP tool used:** `revoke_record_group`
1014
941
 
1015
-
1016
-
1017
942
  ### Groups
1018
-
1019
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).
1020
-
1021
944
  #### List context groups
1022
-
1023
945
  ```text
1024
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.
1025
947
  ```
1026
948
 
1027
-
1028
-
1029
949
  **MCP tool used:** `list_groups`
1030
950
 
1031
-
1032
-
1033
951
  #### Read a record's group grants
1034
-
1035
952
  ```text
1036
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.
1037
954
  ```
1038
955
 
1039
-
1040
-
1041
956
  **MCP tool used:** `list_record_group_grants`
1042
957
 
1043
-
1044
-
1045
958
  #### Create a group
1046
-
1047
959
  ```text
1048
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.
1049
961
  ```
1050
962
 
1051
-
1052
-
1053
963
  **MCP tool used:** `create_group`
1054
964
 
1055
-
1056
-
1057
965
  #### Rename a group
1058
-
1059
966
  ```text
1060
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.
1061
968
  ```
1062
969
 
1063
-
1064
-
1065
970
  **MCP tool used:** `update_group`
1066
971
 
1067
-
1068
-
1069
972
  #### Delete a group
1070
-
1071
973
  ```text
1072
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.
1073
975
  ```
1074
976
 
1075
-
1076
-
1077
977
  **MCP tool used:** `delete_group`
1078
978
 
1079
-
1080
-
1081
979
  #### List group members
1082
-
1083
980
  ```text
1084
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.
1085
982
  ```
1086
983
 
1087
-
1088
-
1089
984
  **MCP tool used:** `list_group_members`
1090
985
 
1091
-
1092
-
1093
986
  #### Add a group member
1094
-
1095
987
  ```text
1096
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.
1097
989
  ```
1098
990
 
1099
-
1100
-
1101
991
  **MCP tool used:** `add_group_member`
1102
992
 
1103
-
1104
-
1105
993
  #### Remove a group member
1106
-
1107
994
  ```text
1108
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.
1109
996
  ```
1110
997
 
1111
-
1112
-
1113
998
  **MCP tool used:** `remove_group_member`
1114
999
 
1115
-
1116
-
1117
1000
  #### Grant a project role to a group
1118
-
1119
1001
  ```text
1120
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.
1121
1003
  ```
1122
1004
 
1123
-
1124
-
1125
1005
  **MCP tool used:** `grant_project_group`
1126
1006
 
1127
-
1128
-
1129
1007
  #### Revoke one project role from a group
1130
-
1131
1008
  ```text
1132
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.
1133
1010
  ```
1134
1011
 
1135
-
1136
-
1137
- **MCP tool used:** `revoke_project_group`
1138
-
1139
-
1012
+ **MCP tool used:** `revoke_project_group`
1140
1013
 
1141
1014
  #### Complete pending encrypted access
1142
-
1143
1015
  ```text
1144
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.
1145
1017
  ```
1146
1018
 
1147
-
1148
-
1149
1019
  **MCP tool used:** `reconcile_group_access`
1150
1020
 
1151
-
1152
-
1153
1021
  ### Record audit
1154
-
1155
1022
  #### Review one record's audit history
1156
-
1157
1023
  ```text
1158
1024
  Show the 25 most recent audit events for record "00000000-0000-4000-8000-000000000020". Summarize actions, actors and timestamps without exposing secret fields.
1159
1025
  ```
1160
1026
 
1161
-
1162
-
1163
1027
  **MCP tool used:** `read_record_audit`
1164
1028
 
1165
-
1166
-
1167
1029
  #### Page and filter one record's audit history
1168
-
1169
1030
  ```text
1170
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.
1171
1032
  ```
1172
1033
 
1173
-
1174
-
1175
1034
  **MCP tool used:** `list_record_audit`
1176
1035
 
1177
-
1178
-
1179
1036
  #### Find unusual record activity
1180
-
1181
1037
  ```text
1182
1038
  Show unusual record activity in project "00000000-0000-4000-8000-000000000010" under account "00000000-0000-4000-8000-000000000001". Group the results by severity.
1183
1039
  ```
1184
1040
 
1185
-
1186
-
1187
1041
  **MCP tool used:** `list_record_anomalies`
1188
1042
 
1189
-
1190
-
1191
1043
  #### Review daily record activity
1192
-
1193
1044
  ```text
1194
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".
1195
1046
  ```
1196
1047
 
1197
-
1198
-
1199
1048
  **MCP tool used:** `list_record_activity`
1200
1049
 
1201
-
1202
-
1203
1050
  #### Review record alerts
1204
-
1205
1051
  ```text
1206
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.
1207
1053
  ```
1208
1054
 
1209
-
1210
-
1211
1055
  **MCP tool used:** `list_record_alerts`
1212
1056
 
1213
-
1214
-
1215
1057
  #### Review secret access events
1216
-
1217
1058
  ```text
1218
1059
  Show the first 25 secret-access events for records in project "00000000-0000-4000-8000-000000000010" under account "00000000-0000-4000-8000-000000000001".
1219
1060
  ```
1220
1061
 
1221
-
1222
-
1223
1062
  **MCP tool used:** `list_record_access`
1224
1063
 
1225
-
1226
-
1227
1064
  ### Providers and credentials
1228
-
1229
1065
  #### List supported AI providers
1230
-
1231
1066
  ```text
1232
1067
  Show the AI providers AIRCTRL supports, including their names, IDs and available configuration. Do not add any credentials.
1233
1068
  ```
1234
1069
 
1235
-
1236
-
1237
1070
  **MCP tool used:** `list_providers`
1238
1071
 
1239
-
1240
-
1241
1072
  #### List provider credentials
1242
-
1243
1073
  ```text
1244
1074
  Show the provider credentials in account "00000000-0000-4000-8000-000000000001". Return labels, IDs, providers and validation status, but never request secret values.
1245
1075
  ```
1246
1076
 
1247
-
1248
-
1249
1077
  **MCP tool used:** `list_provider_credentials`
1250
1078
 
1251
-
1252
-
1253
1079
  #### Add a provider credential
1254
-
1255
1080
  ```text
1256
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.
1257
1082
  ```
1258
1083
 
1259
-
1260
-
1261
1084
  **MCP tool used:** `add_provider_key`
1262
1085
 
1263
-
1264
-
1265
1086
  #### List models for a credential
1266
-
1267
1087
  ```text
1268
1088
  Show the model IDs available through provider credential "00000000-0000-4000-8000-000000000071" in account "00000000-0000-4000-8000-000000000001".
1269
1089
  ```
1270
1090
 
1271
-
1272
-
1273
1091
  **MCP tool used:** `list_provider_models`
1274
1092
 
1275
-
1276
-
1277
1093
  #### Replace a provider key
1278
-
1279
1094
  ```text
1280
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.
1281
1096
  ```
1282
1097
 
1283
-
1284
-
1285
1098
  **MCP tool used:** `rotate_provider_key`
1286
1099
 
1287
-
1288
-
1289
1100
  #### Rename a provider credential
1290
-
1291
1101
  ```text
1292
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.
1293
1103
  ```
1294
1104
 
1295
-
1296
-
1297
1105
  **MCP tool used:** `rename_provider_credential`
1298
1106
 
1299
-
1300
-
1301
1107
  #### Revoke a provider credential
1302
-
1303
1108
  ```text
1304
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.
1305
1110
  ```
1306
1111
 
1307
-
1308
-
1309
1112
  **MCP tool used:** `revoke_provider_credential`
1310
1113
 
1311
-
1312
-
1313
1114
  ### Gateway setup and routing
1314
-
1315
1115
  #### List gateways
1316
-
1317
1116
  ```text
1318
1117
  Show the gateways in project "00000000-0000-4000-8000-000000000010", including each name, ID, provider and active state.
1319
1118
  ```
1320
1119
 
1321
-
1322
-
1323
1120
  **MCP tool used:** `list_gateways`
1324
1121
 
1325
-
1326
-
1327
1122
  #### Create a gateway
1328
-
1329
1123
  ```text
1330
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.
1331
1125
  ```
1332
1126
 
1333
-
1334
-
1335
1127
  **MCP tool used:** `create_gateway`
1336
1128
 
1337
-
1338
-
1339
1129
  #### Set up a complete gateway
1340
1130
 
1341
-
1342
-
1343
1131
  This workflow can add a provider credential, create a gateway and create a one-time gateway token.
1344
1132
 
1345
-
1346
-
1347
1133
  ```text
1348
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.
1349
1135
  ```
1350
1136
 
1351
-
1352
-
1353
1137
  **MCP tool used:** `setup_gateway`
1354
1138
 
1355
-
1356
-
1357
1139
  #### View gateway connection settings
1358
-
1359
1140
  ```text
1360
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.
1361
1142
  ```
1362
1143
 
1363
-
1364
-
1365
1144
  **MCP tool used:** `get_connection_config`
1366
1145
 
1367
-
1368
-
1369
1146
  #### Change gateway routing
1370
-
1371
1147
  ```text
1372
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.
1373
1149
  ```
1374
1150
 
1375
-
1376
-
1377
1151
  **MCP tool used:** `set_routing`
1378
1152
 
1379
-
1380
-
1381
1153
  #### Change gateway limits and behavior
1382
-
1383
1154
  ```text
1384
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.
1385
1156
  ```
1386
1157
 
1387
-
1388
-
1389
1158
  **MCP tool used:** `set_gateway_settings`
1390
1159
 
1391
-
1392
-
1393
1160
  #### Detach a provider credential
1394
-
1395
1161
  ```text
1396
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.
1397
-
1398
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.
1399
1164
  ```
1400
1165
 
1401
-
1402
-
1403
1166
  **MCP tool used:** `detach_gateway_credential`
1404
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
+ ```
1405
1172
 
1173
+ **MCP tool used:** `delete_gateway`
1406
1174
 
1407
- #### 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
+ ```
1408
1180
 
1181
+ **MCP tool used:** `list_gateway_tokens`
1182
+
1183
+ #### Create a gateway token
1409
1184
  ```text
1410
- 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.
1411
1186
  ```
1412
1187
 
1188
+ **MCP tool used:** `create_gateway_token`
1413
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
+ ```
1414
1194
 
1415
- **MCP tool used:** `delete_gateway`
1195
+ **MCP tool used:** `rename_gateway_token`
1416
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
+ ```
1417
1201
 
1202
+ **MCP tool used:** `revoke_gateway_token`
1418
1203
 
1419
- ### 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
+ ```
1420
1208
 
1421
- #### List gateway tokens
1209
+ **MCP tool used:** `delete_gateway_token`
1422
1210
 
1211
+ ### Logs, usage and OpenTelemetry
1212
+ #### Review gateway requests
1423
1213
  ```text
1424
- 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.
1425
1215
  ```
1426
1216
 
1217
+ **MCP tool used:** `read_usage`
1427
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
+ ```
1428
1223
 
1429
- **MCP tool used:** `list_gateway_tokens`
1224
+ **MCP tool used:** `read_gateway_log`
1430
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
+ ```
1431
1230
 
1231
+ **MCP tool used:** `read_gateway_key_access`
1432
1232
 
1433
- #### 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`
1434
1239
 
1240
+ #### Inspect one project usage log
1435
1241
  ```text
1436
- 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.
1437
1243
  ```
1438
1244
 
1245
+ **MCP tool used:** `read_usage_log`
1439
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
+ ```
1440
1251
 
1441
- **MCP tool used:** `create_gateway_token`
1252
+ **MCP tool used:** `read_usage_spend`
1442
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
+ ```
1443
1258
 
1259
+ **MCP tool used:** `read_usage_metrics`
1444
1260
 
1445
- #### 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`
1446
1267
 
1268
+ #### Change OpenTelemetry settings
1447
1269
  ```text
1448
- 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.
1449
1271
  ```
1450
1272
 
1273
+ **MCP tool used:** `set_otel_export`
1451
1274
 
1275
+ ### MCP Gateway prompts
1276
+ #### List project MCP gateways
1277
+ ```text
1278
+ List MCP gateways in project "00000000-0000-4000-8000-000000000010".
1279
+ ```
1452
1280
 
1453
- **MCP tool used:** `rename_gateway_token`
1281
+ **MCP tool used:** `list_mcp_gateways`
1454
1282
 
1455
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`
1456
1290
 
1457
- #### Revoke a gateway token
1458
1291
 
1292
+ #### Review the server catalog
1459
1293
  ```text
1460
- 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.
1461
1295
  ```
1462
1296
 
1297
+ **MCP tool used:** `list_mcp_server_catalog`
1463
1298
 
1464
1299
 
1465
- **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
+ ```
1466
1304
 
1305
+ **MCP tool used:** `get_mcp_gateway`
1467
1306
 
1468
1307
 
1469
- #### Delete a gateway token
1308
+ #### Rename the gateway
1309
+ ```text
1310
+ Rename MCP gateway "00000000-0000-4000-8000-000000000020" to "Engineering tools".
1311
+ ```
1470
1312
 
1313
+ **MCP tool used:** `update_mcp_gateway`
1314
+
1315
+
1316
+ #### Delete the gateway
1471
1317
  ```text
1472
- 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.
1473
1319
  ```
1474
1320
 
1321
+ **MCP tool used:** `delete_mcp_gateway`
1475
1322
 
1476
1323
 
1477
- **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
+ ```
1478
1328
 
1329
+ **MCP tool used:** `update_mcp_runtime`
1479
1330
 
1480
1331
 
1481
- ### 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`
1482
1338
 
1483
- #### Review gateway requests
1484
1339
 
1340
+ #### Connect a catalog server
1485
1341
  ```text
1486
- 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".
1487
1343
  ```
1488
1344
 
1345
+ **MCP tool used:** `create_mcp_server`
1489
1346
 
1490
1347
 
1491
- **MCP tool used:** `read_usage`
1348
+ #### List synchronized tools
1349
+ ```text
1350
+ List synchronized tools for MCP gateway "00000000-0000-4000-8000-000000000020".
1351
+ ```
1492
1352
 
1353
+ **MCP tool used:** `list_mcp_tools`
1493
1354
 
1494
1355
 
1495
- #### 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
+ ```
1496
1360
 
1361
+ **MCP tool used:** `delete_mcp_server`
1362
+
1363
+
1364
+ #### Update a server
1497
1365
  ```text
1498
- 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".
1499
1367
  ```
1500
1368
 
1369
+ **MCP tool used:** `update_mcp_server`
1501
1370
 
1502
1371
 
1503
- **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
+ ```
1504
1376
 
1377
+ **MCP tool used:** `sync_mcp_server`
1505
1378
 
1506
1379
 
1507
- #### 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`
1508
1386
 
1387
+
1388
+ #### List clients
1509
1389
  ```text
1510
- 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".
1511
1391
  ```
1512
1392
 
1393
+ **MCP tool used:** `list_mcp_clients`
1513
1394
 
1514
1395
 
1515
- **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
+ ```
1516
1400
 
1401
+ **MCP tool used:** `create_mcp_client`
1517
1402
 
1518
1403
 
1519
- #### 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`
1520
1410
 
1411
+
1412
+ #### Rename a client
1521
1413
  ```text
1522
- 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".
1523
1415
  ```
1524
1416
 
1417
+ **MCP tool used:** `update_mcp_client`
1525
1418
 
1526
1419
 
1527
- **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
+ ```
1528
1424
 
1425
+ **MCP tool used:** `list_mcp_client_keys`
1529
1426
 
1530
1427
 
1531
- #### 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
+
1532
1435
 
1436
+ #### Revoke a client key
1533
1437
  ```text
1534
- 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.
1535
1439
  ```
1536
1440
 
1441
+ **MCP tool used:** `revoke_mcp_client_key`
1537
1442
 
1538
1443
 
1539
- **MCP tool used:** `read_usage_log`
1444
+ #### List tool policies
1445
+ ```text
1446
+ List policies on MCP gateway "00000000-0000-4000-8000-000000000020".
1447
+ ```
1540
1448
 
1449
+ **MCP tool used:** `list_mcp_policies`
1541
1450
 
1542
1451
 
1543
- #### 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
+
1544
1459
 
1460
+ #### Delete a policy
1545
1461
  ```text
1546
- 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.
1547
1463
  ```
1548
1464
 
1465
+ **MCP tool used:** `delete_mcp_policy`
1549
1466
 
1550
1467
 
1551
- **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
+ ```
1552
1472
 
1473
+ **MCP tool used:** `list_mcp_grants`
1553
1474
 
1554
1475
 
1555
- #### 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`
1556
1482
 
1483
+
1484
+ #### Revoke a grant
1557
1485
  ```text
1558
- 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.
1559
1487
  ```
1560
1488
 
1489
+ **MCP tool used:** `revoke_mcp_grant`
1561
1490
 
1562
1491
 
1563
- **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
+ ```
1564
1496
 
1497
+ **MCP tool used:** `export_mcp_policy`
1565
1498
 
1566
1499
 
1567
- #### 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`
1568
1506
 
1507
+
1508
+ #### Apply policy YAML
1569
1509
  ```text
1570
- 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.
1571
1511
  ```
1572
1512
 
1513
+ **MCP tool used:** `apply_mcp_policy`
1573
1514
 
1574
1515
 
1575
- **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
+ ```
1576
1520
 
1521
+ **MCP tool used:** `list_mcp_calls`
1577
1522
 
1578
1523
 
1579
- #### 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`
1580
1530
 
1531
+
1532
+ #### Read retained payload
1581
1533
  ```text
1582
- 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.
1583
1535
  ```
1584
1536
 
1537
+ **MCP tool used:** `get_mcp_call_payload`
1585
1538
 
1586
1539
 
1587
- **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
+ ```
1588
1544
 
1545
+ **MCP tool used:** `export_mcp_calls_csv`
1589
1546
 
1590
1547
 
1591
1548
  ### When a prompt fails
1592
-
1593
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.
1594
1550
  ## MCP workflow prompts
1595
1551