Admin MCP Server
AIControls exposes its own MCP server so you can query governance data directly from Claude Code or any MCP client.
Admin MCP server
AIControls exposes its own MCP server at https://YOUR_ORG.aicontrols.dev/mcp/admin. This endpoint combines the existing management tools with four governed AIControls Data tools. Connect an MCP client with an administrator personal PAT or a current local session JWT:
Retention cleanup preserves active PATs without an expiration date. These tokens still require an active account and the permissions required by each tool; revoking a token immediately prevents further use.
| Tool | Description |
|---|---|
aicontrols_audit_query | Search audit events by agent, tool, decision, or time range. Each event includes its trusted workload metadata as workloadMetadata when one was recorded |
aicontrols_cost_summary | Get aggregate cost and token usage by developer or model |
aicontrols_identity_baseline | Read an agent’s stored baseline signals, detection status, and data freshness using the configured comparison window |
aicontrols_get_security_finding_context | Read one frozen-scope finding context and revisions; makes no model call |
aicontrols_explain_security_finding | Explicitly generate a potentially paid, cited advisory explanation using accepted context/configuration revisions |
aicontrols_get_security_window_context | Gather full scoped window counts, prior-period coverage and bounded representative metadata without a model call |
aicontrols_explain_security_window | Generate one explicitly consented metadata-only advisory analysis of the gathered window |
aicontrols_risk_scores | Return computed risk scores for agents |
aicontrols_session_list | List active developer sessions with budget utilization |
aicontrols_hitl_list | List pending human-in-the-loop approval requests |
get_k8s_posture_assessment | Read the stored advisory Kubernetes posture assessment, citations, and current evidence baseline |
aicontrols_health | Return the rolled-up health status, its issues, component health, and upstream reachability — all from the same cached snapshot the Health page shows |
aicontrols_policy_list | List loaded policies with match statistics |
nirmata_retrieve | Retrieve the original, uncompressed content of a compressed tool response |
nirmata_pre_compact | Return the compression manifest for a session — the list of compressed tool responses that can still be retrieved before compaction discards them |
data__catalog | Discover authorized reporting datasets and the paged administrator SQL business schema |
data__query | Execute an authorized prepared report, semantic query, or bounded read-only SQLite SQL query |
data__explain_query | Validate and explain a semantic query without executing it |
data__coaching_context | Retrieve bounded, authorized coaching evidence |
nirmata_retrieve
Compressed tool responses carry a retrieval hint of the form nirmata_retrieve hash=<sha256>. Call nirmata_retrieve with that hash to get the original content back:
| Parameter | Required | Description |
|---|---|---|
hash | Yes | The SHA-256 hash from the hint appended to a compressed response |
Originals are retained for 7 days after compression, then purged. Retrieving a hash that has expired or was never issued returns a "not found" error rather than failing silently. See Context Optimization for the full retrieval and retention model.
Authenticate to the admin MCP server with an administrator personal access token or a current local session JWT. A fleet ingest token is refused with 403, even when an administrator created it. Connect it to Claude Code by adding it to your MCP server list in ~/.claude/settings.json:
{
"mcpServers": {
"aicontrols": {
"url": "https://YOUR_ORG.aicontrols.dev/mcp/admin",
"headers": {
"Authorization": "Bearer YOUR_ADMIN_TOKEN"
}
}
}
}
AIControls Data authorization
In Inventory → MCP Servers → Registration, the Built-in Admin MCP endpoint section contains Data tools. The Data group retains its AIControls Data governance identity and is excluded from registered upstream server counts. Its controls and activity apply to Data tools, not the endpoint’s management tools.
Data schema discovery and SQL require an explicit Data grant in addition to authentication. A current personal administrator PAT must identify its immutable account owner and allow the exact qualified tool name (data__catalog, data__query, data__explain_query, or data__coaching_context). A valid empty tool list ([]) permits all four; malformed or null lists, wildcard names, and bare names do not authorize Data calls. These additional scope and grant checks apply to the Data tools. Grant management uses the current local session JWT and cannot be performed with a PAT.
Each Data call uses the ordinary request policies, applicable approvals, response screening, current authority checks, and mandatory Data evidence. SQL accepts read-only queries over reviewed business tables in a sanitized SQLite snapshot; it rejects writes and private credential columns. Prepared and semantic query permissions remain separate from the deployment-wide admin_sql capability. See AIControls Data for schemas, typed results, limits, and grant fields.
In MCP-serving deployments, the administrator endpoint is available on the existing admin listener with the UI disabled, including PAT access when JWT validation is unavailable. Data is unavailable with storage disabled. Finding context and Analyst are unavailable with the web UI disabled. Authz-only deployments retain the 27 management tools without Data when the UI is enabled; with the UI disabled, they have no /mcp/admin endpoint. External clients should send the Bearer header shown above. Current session cookies are validated per request; URL token parameters are rejected before authentication. Applications and service accounts continue to use /mcp with their existing reporting grants.
get_k8s_posture_assessment
This tool is available only in self-managed installations. Kubernetes posture isn't available on Nirmata-hosted workspaces. See Feature availability.
Returns a workload's current deterministic baseline and stored advisory AI Analyst posture assessment. The result includes the rating, findings and fact references, typed context evidence, independent gaps, confidence, model, prompt version, computation time, and stale status. Report references identify Kyverno facts; context: references identify supplied availability, policy, configuration, runtime, or declaration snapshots within assessment.evidence. Context is not a report verdict. The tool is read-only and never invokes an LLM or changes enforcement. The tool uses the integration’s configured cluster; clients do not supply a cluster identifier. An inactive integration returns an explicit error.
| Parameter | Required | Description |
|---|---|---|
namespace | Yes | Workload namespace, or an empty string for a cluster-scoped resource. |
kind | Yes | Kubernetes kind, such as Deployment. |
name | Yes | Workload name. |
The assessment is advisory; a missing or stale assessment does not indicate a clean workload. If the integration is inactive, the tool returns an MCP error with the available reason, even when its reader is configured. See Kubernetes Posture.
See also
Identity baseline
aicontrols_identity_baseline accepts a required agent identifier and reads existing baseline history. It does not start an evaluation or change enforcement. History remains readable when storage is available even if the baseline worker is disabled.
The result includes state, signals, and, when a stored state exists, eventCount, establishedAt, and lastUpdated. detection separates the saved enabled preference, the deploymentEnabled prerequisite, and this replica's runtime status; configurationError identifies an invalid saved preference. dataState describes persisted comparison data: available, awaiting_evaluation, stale, or insufficient_data. A successful worker cycle does not establish fresh stored comparisons or complete detection coverage. Agent-ID history does not establish workload or cluster isolation.
Finding context and Analyst
Both tools require a current active administrator credential. Personal access tokens must be bound to the immutable account ID; legacy email-only tokens must be reissued.
Shared developer endpoints use a separate compatibility rule: UI-account PATs resolve the exact immutable account and use its current email. Proxy-user ID bindings require an active matching proxy account; legacy email-bound developer PATs require an active proxy account with that email. Missing or deleted canonical IDs never fall back to email, and ownerless PATs are rejected. These endpoints retain developer permissions; this compatibility does not grant access to admin MCP.
For these two tools, a PAT with a nonempty allowedTools list must include the exact tool name; an empty list is unrestricted. Wildcard tool names are not expanded. A PAT with any nonempty allowedModels list cannot invoke aicontrols_explain_security_finding: paid generation rejects it before reading source data or resolving a provider, because the configured Analyst model cannot yet be checked against the token's model scope atomically. The same PAT can read context when its tool scope permits. Use an active administrator JWT or a PAT without a model allowlist for explicitly consented paid generation. These restrictions do not change the existing administrative tools.
Read aicontrols_get_security_finding_context first. Both tools take id (the correlated finding group ID) and scope with required frozen UTC from and to bounds; optional exact user, agent, session, workload with cluster, and finding facets (source, detector, eventType, plane, severity) preserve the selected context.
Both tools accept optional contextMode: metadata (the default) or recorded_payload. Retained-content mode is restricted to current active administrators and prepares bounded authorized redacted content, with per-item omissions and snapshot/delta labels. Use the same mode for the read and paid explanation; its revision fences the content sent. No arbitrary capture hashes, client-provided text, archive retrieval, or session expansion are accepted.
For aicontrols_explain_security_finding, also supply:
| Parameter | Required | Value |
|---|---|---|
allowPaidGeneration | Yes | true only after explicit consent to the provider call and potential cost |
expectedContextRevision | Yes | The context projection's contextRevision from the read result |
expectedEvidenceRevision | Yes | The context projection's evidenceRevision, including null when unavailable |
expectedConfigurationID | Yes | The generation configurationID from the read result |
Changed context or configuration requires another read and fresh consent. Output contains advisory observations/next steps with citations and an invocation receipt; missing token/cost data remains unknown. Errors may retain the failed attempt receipt. An answer that fails validation is retried once automatically with a stricter prompt and both attempts are costed; there is no other automatic retry and no enforcement change. Metadata mode sends no captured payload; explicit retained-content mode sends only its authorized bounded redacted evidence. See contextual Analyst.
Window context and Analyst
Read aicontrols_get_security_window_context with scope.from and scope.to defining a frozen half-open UTC window of at most 31 days. Optionally supply one exact recorded user or canonical agent; omit both for global context. Sessions, workloads, clusters and finding facets are rejected. The result includes full retained-source counts, a preceding window of equal duration, coverage and at most eight current-window representative findings. It makes no model call.
Call aicontrols_explain_security_window with the same scope, allowPaidGeneration: true, the returned expectedContextRevision and expectedConfigurationID, and expectedEvidenceRevision: null. No id, contextMode or client prompt is accepted. Both window tools require current administrator authority in admin MCP and honor the exact tool-name PAT allowlist. Paid window generation also rejects PATs with a model allowlist before gathering data or resolving a provider.
The model receives bounded counts and representative metadata, not captured content or raw subject identifiers. Summary citations refer to the gathered periods and coverage; representative citations refer to authorized current-window findings. Groups are not unique attacks, and missing prior records do not establish a zero baseline. Changed revisions require another read and fresh consent. Generation produces an advisory report and attempt receipt without control execution; an answer that fails validation is retried once automatically with a stricter prompt and both attempts are costed.