Governance MCP server

Documentation Index

Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Why an MCP server for governance

• Tool discovery: tools/list enumerates every governance verb with descriptions and input schemas the agent can reason about.
• Type-safe inputs: the same Zod schemas the REST API and CLI consume are exposed via MCP inputSchema, so the agent gets validation feedback before the tool call leaves the client.
• Built-in RBAC + audit: every successful tool call lands in the same audit log as a dashboard click, tagged with surface="mcp" for incident response.

​

Tool naming

governance_ingestion_templates_list
governance_ingestion_templates_admin_list
governance_ingestion_templates_get
governance_ingestion_templates_create
governance_ingestion_templates_update_ottl_rules
governance_ingestion_templates_archive
governance_ingestion_templates_clone_from_platform

governance_user_ingestion_bindings_list
governance_user_ingestion_bindings_install
governance_user_ingestion_bindings_uninstall
governance_user_ingestion_bindings_rotate

governance_anomaly_rules_list
governance_anomaly_rules_create
…

governance_role_bindings_assign_to_user
governance_audit_log_query

​

Authentication

• Project API key as Bearer (Authorization: Bearer <projectApiKey>), the plain read tools work immediately. Sufficient to call governance_*_list and governance_*_get. Admin reads (governance_*_admin_list, which expose ottlRules) and every write tool require a user-bound session and reject a project-key-only caller.
• OAuth (PKCE) flow at /api/mcp/authorize → /oauth/token, required for write tools and admin reads. The OAuth flow captures the user’s id at authorize time, threads it through the session token cache, and surfaces it to governance tools as ctx.callerUserId. Without it, a write tool returns an AUTH_REQUIRED: error pointing the client at the OAuth flow.

// MCP client config, points at the LangWatch instance's MCP endpoint
// (SaaS shown; self-hosted uses your deployment's host).
{
  "mcpServers": {
    "langwatch-governance": {
      "url": "https://app.langwatch.ai/api/mcp"
      // Read-only access: add Authorization: Bearer <projectApiKey>.
      // Read+write access: complete the OAuth PKCE flow at /api/mcp/authorize.
    }
  }
}

​

RBAC enforcement

{
  "isError": true,
  "content": [{ "type": "text", "text": "AUTH_REQUIRED: this tool requires an OAuth-authenticated MCP session. Complete the OAuth flow at /api/mcp/authorize and reconnect." }]
}

{
  "isError": true,
  "content": [{ "type": "text", "text": "FORBIDDEN: caller does not have aiTools:manage on this organization" }]
}

• RBAC check happens at the MCP tool layer, BEFORE the service call, the tool mirrors hasOrganizationPermission from langwatch/src/server/api/rbac.ts and returns FORBIDDEN: early if the required permission is missing. Services trust the surface, they do not gate on the MCP-resolved scope a second time. This split is intentional: the MCP tool owns the RBAC contract for its surface; the service owns the multitenancy + business-logic contract.
• callerUserId flows from the OAuth session, the OAuth PKCE flow at /api/mcp/authorize captures the user’s id, threads it through the session token cache and SessionState, and surfaces it as ctx.callerUserId. For UserIngestionBindingService.{install, uninstall, rotateToken} it’s required (write tools reject with AUTH_REQUIRED: if absent). For IngestionTemplateService authoring methods (which take callerUserId for the audit trail), same plumbing.
• Snake_case ↔ camelCase boundary: MCP tool inputs use snake_case (source_template_id, template_id) per public-surface convention; the tool maps to camelCase (sourceTemplateId, templateId) before calling the service, since service signatures are camelCase. The mapping is the tool’s job, not the service’s.

​

Audit emission

​

Agent setup-from-scratch (the dogfood gate)

1. governance_ingestion_templates_list, read existing platform templates
2. governance_ingestion_templates_clone_from_platform, clone claude_code into the org (delegates to POST /api/governance/ingestion-templates/clone)
3. governance_anomaly_rules_create, rule on org spend > $100/day
4. governance_role_bindings_assign_to_user, give a user governance:view
5. governance_audit_log_query, verify steps 2–4 all emitted audit rows

​

Cross-references

• Governance REST API: the API the MCP tools shell over
• Governance CLI: same surface for shell invocation
• Roles and permissions: RBAC scopes the MCP server enforces
• Audit log: where state-change rows land
• Compliance architecture: how the OCSF v1.1 export consumes the same audit stream
• Spec, specs/ai-gateway/governance/governance-api-cli-mcp-coverage.feature