MCP Server

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

The Control Zero MCP server exposes the /v1 management API -- DLP and policy administration -- plus the cooperative check guard tool as MCP tools, so an AI coding client can administer Control Zero from the 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. The check tool is cooperative: it returns a decision the client is expected to honor, and cannot stop a client that ignores it.

Upgrading from 1.x

Version 2.0 replaced the tool surface and the credential model. The 1.x tools (list_policies, create_policy, delete_policy, provision_safeguards and the others) are gone, as are the MCP resources and prompts. Use 2.0.1 or later: in 2.0.0 a management key was refused at startup and every management tool that writes failed. The CHANGELOG.md shipped inside the package lists every removed tool and changed argument.

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, which is what most MCP clients expect.

Two keys

Key	Environment variable	Prefix	Used for
Management key	CONTROLZERO_MGMT_KEY	cz_mgmt_*	Every dlp_*, policy_*, attachment_*, approval_*, export and apply* tool
Enforcement key	CONTROLZERO_API_KEY	cz_live_* / cz_test_*	The check tool only

An org admin mints a management key in the dashboard. Do not give an agent a management key minted with unattended_publish: true: that flag exists for CI. The server refuses to start with one, and the API refuses a publish-class change from one when the request comes from MCP (403 UNATTENDED_KEY_NOT_ALLOWED_FROM_AGENT) and audits the attempt.

On start the server validates each key it was given: the management key at GET /v1/management/self, the enforcement key at GET /v1/sdk/bootstrap. An invalid key, or a management key that is not a management key, stops the server with a message naming the problem.

CONTROLZERO_API_URL overrides the API base URL (default https://api.controlzero.ai).

Client Configuration

Every snippet sets both keys. Omit whichever one you do not need: the management key drives the administration tools, the enforcement key drives only check.

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_MGMT_KEY": "cz_mgmt_your_key_here",
        "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_MGMT_KEY": "cz_mgmt_your_key_here",
        "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_MGMT_KEY": "cz_mgmt_your_key_here",
        "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_MGMT_KEY": "cz_mgmt_your_key_here",
        "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_MGMT_KEY": "cz_mgmt_your_key_here",
        "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_MGMT_KEY": "cz_mgmt_your_key_here",
        "CONTROLZERO_API_KEY": "cz_live_your_key_here"
      }
    }
  }
}

Available Tools

Management tools (management key)

Tool	What it does	Needs confirm: true
dlp_status	Read whether DLP is on, entitlement, mode and reason
dlp_enable	Turn DLP on or off	yes
dlp_effective	Read the resolved effective DLP configuration for the org or a project
dlp_detectors	List the detector catalog
dlp_rules_list	List DLP rules
dlp_rule_create	Create a DLP rule as a draft
dlp_rule_update	Edit a DLP rule that is not live (requires edit_reason)
dlp_profile_set	Set the org default or a project's detector selection	yes
dlp_test	Test an RE2 pattern against sample text (returns the matched text)
policies_list	List the policy library
policy_create	Create a policy and its draft v1
policy_get	Get a policy from the library
policy_version_create	Create a new draft version of a policy
policy_validate	Validate a policy document without saving it
attachment_create	Attach a library policy to a project	yes, when active
attachment_delete	Detach a policy attachment from a project	yes, when active
export	Export DLP settings, rules, policies and attachments as one YAML document
apply_dry_run	Plan an org document against the org without changing anything
apply	Apply an org document	yes
approvals_list	List pending and recent management approvals
approval_approve	Approve an approval raised by a different principal	yes
approval_reject	Reject a pending approval	yes

Publishing a DLP rule, rolling it back, and publishing a policy draft are dashboard operations; there is no MCP tool for them.

Enforcement tool (enforcement key)

Tool	What it does
check	Ask whether a proposed tool call is allowed by the project's DLP rules. See MCP Cooperative Guard.

Confirmation and second principals

Call a tool that needs confirm once without it to get a preview ({"preview": ..., "confirm_required": true}); nothing changes. Call it again with confirm: true to apply. For the DLP, attachment and apply tools the API enforces this, so a direct HTTP caller gets the same gate. A draft_only or paused attachment governs nothing and is created or removed without confirmation. approval_approve and approval_reject apply the gate in the MCP server itself: the API's approve and reject routes have no preview step, so a direct HTTP call decides immediately.

A publish-class change made with a management key -- turning DLP on or off, changing a detector selection, an active attach or detach, or an apply that publishes -- waits for a different principal to approve it: a dashboard admin, or a second management key using approval_approve. The API rejects self-approval.

Example Usage

"Show me the DLP rules for this org, and which ones are still drafts."

"Create a draft DLP rule named internal-ticket-ids that masks TKT-[0-9]{6} in SDK and gateway traffic."

"Export the org's configuration, then plan it again with apply_dry_run and tell me what would change."

Hosted MCP: COMING SOON -- Running the MCP server locally is available on all tiers today. The managed endpoint is not yet live. See Hosted MCP Server.

Related

• MCP Cooperative Guard: the check tool in detail.
• Governing MCP tool calls: Govern MCP tool access with policies.
• MCP Integration: MCP integration overview.
• API Reference: Full API documentation.