MCP Server

Overview

AI Governance Platform exposes a Model Context Protocol server as a stateless transport adapter over the existing REST control plane. The MCP server does not own governance rules, persistence, provider behavior, or orchestration semantics. Each tool validates input, calls exactly one REST endpoint, maps the REST response, and translates REST errors into tool errors.

Protocol version and state

Native Streamable HTTP prefers MCP 2026-07-28. Each request carries its protocol metadata, client identity, and capabilities, so it does not need aninitialize handshake, an Mcp-Session-Id, or sticky routing. That makes the endpoint suitable for ordinary load balancers and horizontally scaled deployments.

This changes protocol state, not governance state. Decisions, audit records, jobs, replay executions, and assets remain durable control-plane resources. A workflow that needs continuity passes an explicit identifier, such as a job or replay ID, in its tool arguments rather than relying on a hidden transport session.

The endpoint continues to accept legacy session-based clients during the migration. New clients should request 2026-07-28; see the Streamable HTTP guide for the exact request.

MCP Interfaces

AI Governance Platform offers three MCP interfaces. They expose the same canonical tool registry, but serve different client environments. Choose the interface your client already understands rather than adding an unnecessary proxy.

Multi-Organization Context

Control-plane tools accept a required context object containing organization_id and, for project operations, project_id. Actor identity is resolved by the server and is not accepted as an impersonation argument. Discovery and administration tools include organization.*, project.*, membership.*, role_assignment.*, authorization.permissions, and context.current.

MCPO & REST Proxy

MCPO is the OpenAPI proxy used to expose MCP tools as ordinary HTTP endpoints. It provides Swagger UI and REST compatibility for clients that cannot connect directly to a stdio MCP server. MCPO does not replace AI Governance Platform authorization; every proxied call still reaches the REST control plane with an authenticated service identity.

./scripts/mcp/start-mcp.sh
# Open the generated API surface
open http://127.0.0.1:8001/docs

For setup, authentication, and client-specific guidance, see the MCPO OpenAPI guide.

Authentication

Authentication depends on the interface. MCPO and local stdio automation use the Keycloak ai-governance-mcp confidential client with client credentials. The short-lived token is refreshed before expiry, and its service-account actor is discovered during startup.

Native Streamable HTTP is different: a human client such as VS Code signs in through the browser and AI Governance Platform uses that person's token. In every case, a valid token proves identity only. Membership and role checks still decide whether the actor can use a tool in an organization or project.

Using stdio user is expected for an interactive MCP client. When VS Code opens the Keycloak page, it needs to know which human is using MCP. In local development, that human is the demo user studio, so you enter the studio password. You do not need a separate "MCP human user." The same person can sign in to both Studio and VS Code MCP:

Your human account: studio
    ├─ signs into Studio
    └─ signs into VS Code MCP

The ai-governance-mcp-vscode client identifies the application (VS Code); studio identifies the person. The password is submitted to Keycloak, not stored by the MCP server.

Tool names by interface

The Core registry groups tools with dots, for exampleprovider.list. Stdio code and MCPO keep those canonical names. Native Streamable HTTP converts dots to underscores because many MCP clients, including VS Code, only accept letters, numbers, underscores, and hyphens in a tool name.

Where you call the tool        Use this name
Python, stdio, or MCPO         provider.list
Native HTTP in VS Code         provider_list

Python, stdio, or MCPO         context.current
Native HTTP in VS Code         context_current

This is a transport detail, not a different capability. Both names reach the same governed AI Governance Platform operation.

Tool Groups

Provider Tools

• provider.list — list available evaluation providers

Registry Tools

• registry.list_prompts, registry.get_prompt
• registry.list_models, registry.get_model
• registry.list_datasets, registry.get_dataset

Evaluation Tools

• evaluation.history, evaluation.latest
• evaluation.get, evaluation.metrics
• evaluation.submit_async

Experiment Tools

• experiment.list, experiment.get
• experiment.candidates, experiment.runs
• experiment.compare_candidates, experiment.leaderboard
• experiment.create
• experiment.add_candidate, experiment.run_async

Governance Tools

• governance.compare, governance.drift
• governance.report, governance.summarize_experiment
• governance.explain_candidate, governance.compare_candidates
• governance.investigate_execution, governance.investigate_job
• governance.investigate_evaluation, governance.investigate_audit
• governance.explain_drift, governance.summarize_drift
• governance.generate_experiment_report, governance.generate_evaluation_report
• governance.generate_drift_report, governance.generate_investigation_report

Governance Decision Tools

• governance_decision.evaluate, governance_decision.get
• governance_decision.list, governance_decision.evidence
• governance_decision.lineage, governance_decision.explain

Job Tools

• job.list, job.status
• job.cancel, job.retry

Ontology Graph Tools

• ontology_graph.get_entity, ontology_graph.get_relationship
• ontology_graph.get_relationships, ontology_graph.neighbourhood
• ontology_graph.upstream, ontology_graph.downstream
• ontology_graph.find_paths

MCP Audit Tools

• mcp_audit.list, mcp_audit.get
• mcp_audit.find_by_request, mcp_audit.find_by_correlation

Write Envelope

Controlled write tools share this required envelope:

{
  "request_id": "...",
  "idempotency_key": "...",
  "requested_by": "...",
  "actor_type": "HUMAN | AGENT | SERVICE",
  "reason": "...",
  "dry_run": false,
  "metadata": {}
}

Optional correlation fields include correlation_id, agent_name, agent_session_id, client_name, and client_version.

Dry Run

When dry_run is true, MCP validates the envelope and tool-specific schema, records the MCP audit entry, and returns a validation result without calling REST or creating a job. Business validation remains in REST/application services for non-dry-run requests.

MCP Execution Audit

Controlled write tools record MCP execution audit entries before calling REST and update the same durable audit row after completion. Audit records include request/correlation IDs, actor metadata, tool name, operation details, canonical request hash, safe request summary, dry-run status, job ID, result reference, error details, and duration.

Full request payloads are not blindly stored. Sensitive fields such as provider_config, API keys, tokens, passwords, and secrets are redacted from the audit summary.

Settings Tools

• settings.list and settings.get — expose effective typed configuration
• settings.categories — list the registry navigation model
• settings.validate — validate a proposed value without persistence
• settings.update — write a mutable runtime value

Runtime Boundary

AI Assistant
  → MCP Tool
  → REST Client
  → AI Governance Platform REST Control Plane
  → Application Services

MCP handlers must not import repositories, provider SDKs, domain construction logic, or worker operations. Controlled writes return job references whenever they submit execution work.