MCP Server

Overview

Kavach 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.

MCP Interfaces

Kavach 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 Kavach 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

The MCP server uses the Keycloak kavach-mcp confidential client with client credentials. The short-lived token is refreshed before expiry. The service-account actor is discovered during startup and written to .env.mcp.generated; developers should not manually hard-code the actor ID in a fresh setup.

A valid token is not sufficient by itself. Grant the service account the required organization/project roles in Studio under Organization → Access; tenant membership and permission checks apply to every tool.

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
  → Kavach 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.