@airctrl/mcp 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -14,6 +14,29 @@ npx --yes @airctrl/mcp
14
14
 
15
15
  Requires Node.js 22.x.
16
16
 
17
+ ## Current release
18
+
19
+ **Coordinated package version:** `0.5.0`
20
+
21
+ ### SDK
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.
26
+
27
+ ### CLI
28
+
29
+ - Added gateway log `--search` and `--status-class` filters plus gateway-scoped usage metrics and spend flags.
30
+
31
+ ### MCP
32
+
33
+ - Added the same gateway log search and scoped metrics inputs to `read_usage`, `read_usage_metrics`, and `read_usage_spend`.
34
+
35
+ ### Release engineering
36
+
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.
39
+
17
40
  ## MCP setup
18
41
 
19
42
  `@airctrl/mcp` runs locally on your machine or in infrastructure you control. It uses `@airctrl/sdk` for AIRCTRL operations.
@@ -269,10 +292,25 @@ These metadata tools are human-only. Service Account creation, state changes, cr
269
292
  | Tool | Inputs | Purpose |
270
293
  |---|---|---|
271
294
  | `read_record_audit` | `recordId`; optional `limit` | Read audit events for one record. |
295
+ | `list_record_audit` | `recordId`; optional `cursor`, `action`, `actor`, `from`, `to`, `limit`, legacy `offset` | Read a stable filtered audit-event page. |
272
296
  | `list_record_anomalies` | Optional `accountId`, `scopeType`, `scopeId` | List unusual record events. |
273
297
  | `list_record_activity` | `day`; optional `accountId`, `scopeType`, `scopeId` | Read one UTC day's record activity. |
274
- | `list_record_alerts` | Optional `accountId`, `scopeType`, `scopeId`, `limit`, `offset` | Read the record alert feed. |
275
- | `list_record_access` | Optional `accountId`, `scopeType`, `scopeId`, `limit`, `offset`, `actions` | Read the record access feed. |
298
+ | `list_record_alerts` | Optional `accountId`, `scopeType`, `scopeId`, `cursor`, `limit`, legacy `offset` | Read the record alert feed. |
299
+ | `list_record_access` | Optional `accountId`, `scopeType`, `scopeId`, `cursor`, `limit`, legacy `offset`, `actions` | Read the record access feed. |
300
+
301
+ Ask an agent for a bounded page and keep the returned cursor opaque:
302
+
303
+ ```text
304
+ List the first 25 record.update audit events for record
305
+ 00000000-0000-4000-8000-000000000020 where the actor contains "david".
306
+ Return pagination.next_cursor without decoding it.
307
+ ```
308
+
309
+
310
+
311
+ **MCP tool used:** `list_record_audit`
312
+
313
+
276
314
 
277
315
  ### Providers and gateway setup
278
316
 
@@ -281,14 +319,14 @@ These metadata tools are human-only. Service Account creation, state changes, cr
281
319
  | `list_providers` | None | List enabled AI providers. |
282
320
  | `list_provider_credentials` | `accountId` | List safe provider credential metadata. |
283
321
  | `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`. |
284
- | `list_provider_models` | `accountId`, `credentialId` | List models available through a provider credential. |
322
+ | `list_provider_models` | `accountId`, `credentialId` | List models available through a provider credential, including official numeric rates, `displayText`, and context-tiered `rateCard` data. |
285
323
  | `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. |
286
324
  | `rename_provider_credential` | `accountId`, `credentialId`, `label` | Change a provider credential label. |
287
325
  | `revoke_provider_credential` | `accountId`, `credentialId` | Revoke a provider credential. |
288
326
  | `list_gateways` | `projectId` | List gateways in one project. |
289
327
  | `create_gateway` | `accountId`, `projectId`, `name`; optional `slug`, `credentialBindings` | Create a gateway, optionally with explicit credential/model bindings. |
290
328
  | `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. |
291
- | `get_connection_config` | `gatewayId` | Return compatibility and native OpenAI, Anthropic, Gemini, Mistral and OpenRouter URLs, plus supported realtime WebSocket URLs. |
329
+ | `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. |
292
330
  | `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. |
293
331
  | `set_gateway_settings` | `accountId`, `gatewayId`; at least one optional settings field | Update limits, logging, guardrails or allowed models. |
294
332
  | `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. |
@@ -308,13 +346,13 @@ These metadata tools are human-only. Service Account creation, state changes, cr
308
346
 
309
347
  | Tool | Inputs | Purpose |
310
348
  |---|---|---|
311
- | `read_usage` | `gatewayId`; optional `since`, `provider`, `model`, `status`, `limit`, `offset` | Read filtered request metadata for one gateway. |
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. |
312
350
  | `read_gateway_log` | `gatewayId`, `logId` | Read stored request and response bodies for one gateway log. |
313
351
  | `read_gateway_key_access` | `gatewayId`; optional `outcome`, `since`, `limit`, `offset` | List provider credential access outcomes. |
314
- | `list_usage_logs` | `projectId`; optional `since`, `provider`, `model`, `status`, `gatewayId`, `limit`, `offset` | List usage across a project. |
352
+ | `list_usage_logs` | `projectId`; optional `since`, `provider`, `model`, `status`, `gatewayId`, `cursor`, `limit`, legacy `offset` | List usage across a project. |
315
353
  | `read_usage_log` | `projectId`, `logId` | Read one project's stored request and response bodies. |
316
- | `read_usage_spend` | `projectId` | Compare spend with effective limits. |
317
- | `read_usage_metrics` | `projectId`; optional `since`, `bucket` | Read request, error, token, latency and spend metrics. |
354
+ | `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. |
318
356
  | `get_otel_export` | `accountId`, `gatewayId` | Read safe OpenTelemetry export settings. |
319
357
  | `set_otel_export` | `accountId`, `gatewayId`; optional export fields | Update OpenTelemetry export settings. |
320
358
 
@@ -325,7 +363,7 @@ These metadata tools are human-only. Service Account creation, state changes, cr
325
363
  - `read_record.scope` accepts sections only: `fields`, `meta`, `owner`, `access`, or `full`. It does not select individual field names.
326
364
  - 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.
327
365
  - `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.
328
- - Pagination starts at `offset: 0`. Keep `limit` small when an agent only needs a summary.
366
+ - Log pagination starts without a cursor. Continue with `pagination.next_cursor`, the same scope and the exact same filters. Cursors cannot be combined with legacy `offset`. Keep `limit` small when an agent only needs a summary.
329
367
  - `accountId` selects the account. It does not grant access to it.
330
368
  - `projectId`, `recordId`, `gatewayId`, `credentialId` and `tokenId` select resources. AIRCTRL still checks RBAC and resource access.
331
369
  - Optional booleans must be real JSON booleans such as `true`, not strings such as `"true"`.
@@ -493,6 +531,19 @@ After confirmation, revoke only that token and report its final status.
493
531
 
494
532
 
495
533
 
534
+ ### OAuth partner Apps
535
+
536
+ The MCP server has no OAuth App credential mode, authorization-code flow, or
537
+ installation/protection lifecycle tools. Do not place OAuth client secrets, authorization codes,
538
+ access tokens, or refresh tokens in MCP configuration or an agent conversation. Neither is a
539
+ confidential partner token store, and a hosted MCP would violate the partner-backend boundary.
540
+
541
+ Implement OAuth partner flows through direct HTTP/OpenAPI or `OAuthPartnerClient` in the partner's
542
+ confidential backend. See [OAuth partner integrations](https://docs.airctrl.dev/guides/oauth-partner-integrations),
543
+ [OAuth protocol](https://docs.airctrl.dev/reference/oauth-protocol), and
544
+ [OAuth protection API](https://docs.airctrl.dev/reference/oauth-protections). MCP may manage ordinary gateways with a
545
+ separately authorized human PAT; those tools do not act as an OAuth installation.
546
+
496
547
  ### Tool results
497
548
 
498
549
  API-backed tools return structured JSON from `@airctrl/sdk`. Read tools return the requested resource, list tools return arrays or paginated data, and write tools return the new or updated resource. One-time credentials are the exception: their plaintext is present only in the successful creation result.
@@ -1113,6 +1164,18 @@ Show the 25 most recent audit events for record "00000000-0000-4000-8000-0000000
1113
1164
 
1114
1165
 
1115
1166
 
1167
+ #### Page and filter one record's audit history
1168
+
1169
+ ```text
1170
+ 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
+ ```
1172
+
1173
+
1174
+
1175
+ **MCP tool used:** `list_record_audit`
1176
+
1177
+
1178
+
1116
1179
  #### Find unusual record activity
1117
1180
 
1118
1181
  ```text
@@ -1516,7 +1579,7 @@ Show the OpenTelemetry export settings for gateway "00000000-0000-4000-8000-0000
1516
1579
  #### Change OpenTelemetry settings
1517
1580
 
1518
1581
  ```text
1519
- Enable OpenTelemetry metrics and traces for gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001". Send them to "https://otel.example.com/v1/traces" and read headers from "OTEL_EXPORT_HEADERS". Show the destination and enabled data, then wait for my confirmation.
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.
1520
1583
  ```
1521
1584
 
1522
1585
 
@@ -1691,7 +1754,7 @@ Replace provider credential "00000000-0000-4000-8000-000000000071" in account "0
1691
1754
  ### Configure OpenTelemetry and verify safe state
1692
1755
 
1693
1756
  ```text
1694
- For gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001", show the current OpenTelemetry state, endpoint and export flags without requesting header values. Prepare to enable metrics and traces to "https://otel.example.com/v1/traces" using headers from "OTEL_EXPORT_HEADERS". Wait for my confirmation, apply the change, and report only the final safe settings.
1757
+ For gateway "00000000-0000-4000-8000-000000000030" in account "00000000-0000-4000-8000-000000000001", show the current OpenTelemetry state, endpoint and export flags without requesting header values. Prepare to enable metrics and traces to the base endpoint "https://otel.example.com" using headers from "OTEL_EXPORT_HEADERS"; request events are automatic while export is enabled. Include bodies only when gateway Log bodies is enabled. Wait for my confirmation, apply the change, and report only the final safe settings.
1695
1758
  ```
1696
1759
 
1697
1760
 
package/dist/index.js CHANGED
@@ -14,7 +14,7 @@ import { registerTools } from './tools.js';
14
14
  */
15
15
  const config = loadConfig();
16
16
  const client = createClient(createMcpClientOptions(config));
17
- const server = new McpServer({ name: 'airctrl', version: '0.3.0' });
17
+ const server = new McpServer({ name: 'airctrl', version: '0.5.0' });
18
18
  registerTools(server, client, config);
19
19
  server.registerTool('airctrl_status', {
20
20
  title: 'AIRCTRL MCP status',
package/dist/tools.js CHANGED
@@ -52,6 +52,10 @@ function buildConnectionConfig(config, gw) {
52
52
  mistral: connection.mistralBaseUrl,
53
53
  openrouter: connection.openrouterBaseUrl,
54
54
  hitheo: connection.hitheoBaseUrl,
55
+ groq: connection.groqBaseUrl,
56
+ novita: connection.novitaBaseUrl,
57
+ atlas: connection.atlasBaseUrl,
58
+ xai: connection.xaiBaseUrl,
55
59
  },
56
60
  realtime: {
57
61
  openai: `${connection.openaiRealtimeUrl}?model=<model>`,
@@ -418,6 +422,9 @@ export function registerTools(inputServer, client, config) {
418
422
  provider: z.string().max(64).optional(),
419
423
  model: z.string().max(200).optional(),
420
424
  status: z.number().int().min(100).max(599).optional(),
425
+ statusClass: z.enum(['2xx', '4xx', '5xx', 'other']).optional(),
426
+ search: z.string().min(2).max(200).optional(),
427
+ cursor: z.string().max(2048).optional(),
421
428
  limit: z.number().int().min(1).max(200).optional(),
422
429
  offset: z.number().int().min(0).optional(),
423
430
  },
@@ -432,6 +439,7 @@ export function registerTools(inputServer, client, config) {
432
439
  model: z.string().max(200).optional(),
433
440
  status: z.number().int().min(100).max(599).optional(),
434
441
  gatewayId: z.string().uuid().optional(),
442
+ cursor: z.string().max(2048).optional(),
435
443
  limit: z.number().int().min(1).max(200).optional(),
436
444
  offset: z.number().int().min(0).optional(),
437
445
  },
@@ -444,8 +452,11 @@ export function registerTools(inputServer, client, config) {
444
452
  server.registerTool('read_usage_spend', {
445
453
  title: 'Read project spend',
446
454
  description: 'Read spend versus configured caps for a project.',
447
- inputSchema: { projectId: z.string().uuid() },
448
- }, ({ projectId }) => run(() => client.getUsageSpend(projectId)));
455
+ inputSchema: {
456
+ projectId: z.string().uuid(),
457
+ gatewayId: z.string().uuid().optional(),
458
+ },
459
+ }, ({ projectId, gatewayId }) => run(() => client.getUsageSpend(projectId, gatewayId)));
449
460
  server.registerTool('read_usage_metrics', {
450
461
  title: 'Read project usage metrics',
451
462
  description: 'Read bucketed usage metrics and KPIs for a project.',
@@ -453,8 +464,13 @@ export function registerTools(inputServer, client, config) {
453
464
  projectId: z.string().uuid(),
454
465
  since: z.string().optional(),
455
466
  bucket: z.enum(['hour', 'day']).optional(),
467
+ gatewayId: z.string().uuid().optional(),
468
+ provider: z.string().max(64).optional(),
469
+ model: z.string().max(200).optional(),
470
+ statusClass: z.enum(['2xx', '4xx', '5xx', 'other']).optional(),
471
+ search: z.string().min(2).max(200).optional(),
456
472
  },
457
- }, ({ projectId, since, bucket }) => run(() => client.getUsageMetrics(projectId, { since, bucket })));
473
+ }, ({ projectId, ...input }) => run(() => client.getUsageMetrics(projectId, input)));
458
474
  server.registerTool('get_connection_config', {
459
475
  title: 'Get connection config',
460
476
  description: 'Compose the copy-paste connection config for a gateway: the data-plane base URLs for the OpenAI SDK (/compat), OpenAI-native, and Claude Code (/anthropic). Pair with a token from create_gateway_token.',
@@ -629,6 +645,7 @@ export function registerTools(inputServer, client, config) {
629
645
  endpoint: z.string().nullable().optional(),
630
646
  exportMetrics: z.boolean().optional(),
631
647
  exportTraces: z.boolean().optional(),
648
+ exportBodies: z.boolean().optional(),
632
649
  headersEnv: z.string().optional(),
633
650
  clearHeaders: z.boolean().optional(),
634
651
  },
@@ -667,10 +684,11 @@ export function registerTools(inputServer, client, config) {
667
684
  gatewayId: z.string().uuid(),
668
685
  outcome: z.enum(['granted', 'denied', 'error']).optional(),
669
686
  since: z.string().optional(),
687
+ cursor: z.string().max(4096).optional(),
670
688
  limit: z.number().int().min(1).max(200).optional(),
671
689
  offset: z.number().int().min(0).optional(),
672
690
  },
673
- }, ({ gatewayId, outcome, since, limit, offset }) => run(() => client.listGatewayKeyAccess(gatewayId, { outcome, since, limit, offset })));
691
+ }, ({ gatewayId, outcome, since, cursor, limit, offset }) => run(() => client.listGatewayKeyAccess(gatewayId, { outcome, since, cursor, limit, offset })));
674
692
  server.registerTool('list_provider_credentials', {
675
693
  title: 'List provider credentials',
676
694
  description: 'List provider credential metadata for an account. Secret values are never returned.',
@@ -723,6 +741,20 @@ export function registerTools(inputServer, client, config) {
723
741
  limit: z.number().int().min(1).max(1000).optional(),
724
742
  },
725
743
  }, ({ recordId, limit }) => run(() => client.getRecordAudit(recordId, limit)));
744
+ server.registerTool('list_record_audit', {
745
+ title: 'List record audit events',
746
+ description: 'List one stable cursor page of audit-event metadata for a record. Secret values are never returned.',
747
+ inputSchema: {
748
+ recordId: z.string().uuid(),
749
+ limit: z.number().int().min(1).max(100).optional(),
750
+ offset: z.number().int().min(0).optional(),
751
+ cursor: z.string().max(4096).optional(),
752
+ action: z.string().max(160).optional(),
753
+ actor: z.string().max(254).optional(),
754
+ from: z.string().optional(),
755
+ to: z.string().optional(),
756
+ },
757
+ }, ({ recordId, ...input }) => run(() => client.listRecordAudit(recordId, input)));
726
758
  server.registerTool('update_record_metadata', {
727
759
  title: 'Update record metadata',
728
760
  description: 'Update a record name, tags, due date, or rotation interval without changing ciphertext.',
@@ -862,7 +894,8 @@ export function registerTools(inputServer, client, config) {
862
894
  accountId: z.string().uuid().optional(),
863
895
  scopeType: z.enum(['user', 'project']).optional(),
864
896
  scopeId: z.string().uuid().optional(),
865
- limit: z.number().int().min(1).max(200).optional(),
897
+ cursor: z.string().max(4096).optional(),
898
+ limit: z.number().int().min(1).max(100).optional(),
866
899
  offset: z.number().int().min(0).optional(),
867
900
  },
868
901
  }, (input) => run(() => client.listRecordAlerts(input)));
@@ -873,7 +906,8 @@ export function registerTools(inputServer, client, config) {
873
906
  accountId: z.string().uuid().optional(),
874
907
  scopeType: z.enum(['user', 'project']).optional(),
875
908
  scopeId: z.string().uuid().optional(),
876
- limit: z.number().int().min(1).max(200).optional(),
909
+ cursor: z.string().max(4096).optional(),
910
+ limit: z.number().int().min(1).max(100).optional(),
877
911
  offset: z.number().int().min(0).optional(),
878
912
  actions: z.array(z.string().min(1)).optional(),
879
913
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@airctrl/mcp",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "description": "Local/self-hosted MCP server for AIRCTRL records, projects, gateways and usage workflows.",
6
6
  "license": "UNLICENSED",
@@ -37,9 +37,9 @@
37
37
  "start": "node dist/index.js"
38
38
  },
39
39
  "dependencies": {
40
- "@airctrl/sdk": "0.3.0",
40
+ "@airctrl/sdk": "0.5.0",
41
41
  "@modelcontextprotocol/sdk": "1.32.1",
42
- "zod": "4.4.3"
42
+ "zod": "4.6.7"
43
43
  },
44
44
  "devDependencies": {
45
45
  "@types/node": "22.20.0"