Skip to main content

MCP Server

Supported modes: Hosted Local Available in: Free Solo Teams (hosted MCP: COMING SOON)

The Control Zero MCP server lets you manage governance directly from AI coding clients. Create projects, define policies, review audit logs, and manage secrets, all without leaving your editor.

Scope

This server administers Control Zero; it does not govern the MCP client's own tool calls. Govern Claude Code actions with coding hooks, and govern tool calls in your own application with the SDK.

What It Does​

The MCP server exposes Control Zero's management API as MCP tools. Any MCP-compatible client can call these tools, giving your AI coding assistant full access to your governance configuration.

Use cases:

  • Ask your AI assistant to create a new policy for your project
  • Review recent audit log entries from your editor
  • Manage secrets and API keys without switching to the dashboard
  • Scan projects for governance gaps inline (requires the unpublished CLI scanner)

Installation​

Configure the Control Zero registry once: add @controlzero:registry=https://npm.controlzero.ai to your .npmrc (or run npm config set @controlzero:registry https://npm.controlzero.ai). It applies to npm install and npx for the whole @controlzero scope.

npx -p @controlzero/mcp-server controlzero-mcp

The -p ... controlzero-mcp form is required. The package ships two binaries (controlzero-mcp for stdio and controlzero-mcp-hosted for HTTP), neither of which matches the package name, so a bare npx @controlzero/mcp-server fails with could not determine executable to run.

If you installed globally with npm install -g @controlzero/mcp-server, run controlzero-mcp directly instead.

The server starts on stdio transport by default, which is what most MCP clients expect.

Client Configuration​

Claude Desktop​

Add to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "controlzero": {
      "command": "npx",
      "args": ["-p", "@controlzero/mcp-server", "controlzero-mcp"],
      "env": {
        "CONTROLZERO_API_KEY": "cz_live_your_key_here"
      }
    }
  }
}

Claude Code​

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "controlzero": {
      "command": "npx",
      "args": ["-p", "@controlzero/mcp-server", "controlzero-mcp"],
      "env": {
        "CONTROLZERO_API_KEY": "cz_live_your_key_here"
      }
    }
  }
}

Cursor​

In Cursor settings, navigate to MCP Servers and add:

{
  "controlzero": {
    "command": "npx",
    "args": ["-p", "@controlzero/mcp-server", "controlzero-mcp"],
    "env": {
      "CONTROLZERO_API_KEY": "cz_live_your_key_here"
    }
  }
}

Windsurf​

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "controlzero": {
      "command": "npx",
      "args": ["-p", "@controlzero/mcp-server", "controlzero-mcp"],
      "env": {
        "CONTROLZERO_API_KEY": "cz_live_your_key_here"
      }
    }
  }
}

VS Code​

Add to your VS Code MCP settings (.vscode/mcp.json):

{
  "servers": {
    "controlzero": {
      "command": "npx",
      "args": ["-p", "@controlzero/mcp-server", "controlzero-mcp"],
      "env": {
        "CONTROLZERO_API_KEY": "cz_live_your_key_here"
      }
    }
  }
}

Gemini CLI​

Add to your Gemini CLI MCP configuration:

{
  "mcpServers": {
    "controlzero": {
      "command": "npx",
      "args": ["-p", "@controlzero/mcp-server", "controlzero-mcp"],
      "env": {
        "CONTROLZERO_API_KEY": "cz_live_your_key_here"
      }
    }
  }
}

Available Tools​

The MCP server exposes 7 tools for managing your Control Zero governance:

Policy Management​

ToolDescription
list_policiesList all active governance policies
create_policyCreate a new governance policy (Model Block, Cost Cap, PII, Identity)
update_policyUpdate an existing governance policy
delete_policyDelete a governance policy
provision_safeguardsRapidly provision standard security safeguards (PII block + cost cap)
check_policyPre-flight check whether a specific action would be allowed or denied by active governance policies
expert_queryQuery the Control Zero expert knowledge base (topics: pii-patterns, best-practices)

Available Resources​

The server also exposes read-only reference resources:

URIDescription
cz://docs/pii-patternsPII regex reference with GDPR / HIPAA / PCI DSS mappings
cz://docs/best-practicesAI governance best practices (fail-closed, audit-before-deny, least privilege)

Available Prompts​

PromptArgumentsDescription
setup-hipaa-complianceproject_name (req.)Template for provisioning PII DLP rules; mask rules redact only on Claude Code and Gemini CLI through the Python SDK and deny elsewhere

Example Usage​

Once configured, you can interact with Control Zero through natural language in your AI coding client:

Create a policy:

"Create a Control Zero policy called 'read-only-agent' that allows database:query but denies database:execute and database:delete for the project my-agent."

Review audit logs:

"Show me the last 10 denied actions in the audit log for project my-agent."

Manage secrets:

"List all secrets stored in my Control Zero project."

Check project status:

"What policies are active in my production-agents project?"

Hosted MCP: COMING SOON -- Running the MCP server locally is available on all tiers today. Hosted MCP provisioning (managed, no local install needed) is not yet live; when it ships it will be a Teams-tier feature. See Hosted MCP Server.

Authentication​

The MCP server authenticates using your Control Zero API key. Pass it via the CONTROLZERO_API_KEY environment variable in your client configuration.

For organization-level operations (listing projects, creating projects), use an organization token. For project-scoped operations, a project API key is sufficient.