メインコンテンツまでスキップ
このページはまだお使いの言語に翻訳されていないか、翻訳が技術レビュー待ちです。以下には英語の原文を表示しています。 英語のページを開く

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​

KeyEnvironment variablePrefixUsed for
Management keyCONTROLZERO_MGMT_KEYcz_mgmt_*Every dlp_*, policy_*, attachment_*, approval_*, export and apply* tool
Enforcement keyCONTROLZERO_API_KEYcz_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)​

ToolWhat it doesNeeds confirm: true
dlp_statusRead whether DLP is on, entitlement, mode and reason
dlp_enableTurn DLP on or offyes
dlp_effectiveRead the resolved effective DLP configuration for the org or a project
dlp_detectorsList the detector catalog
dlp_rules_listList DLP rules
dlp_rule_createCreate a DLP rule as a draft
dlp_rule_updateEdit a DLP rule that is not live (requires edit_reason)
dlp_profile_setSet the org default or a project's detector selectionyes
dlp_testTest an RE2 pattern against sample text (returns the matched text)
policies_listList the policy library
policy_createCreate a policy and its draft v1
policy_getGet a policy from the library
policy_version_createCreate a new draft version of a policy
policy_validateValidate a policy document without saving it
attachment_createAttach a library policy to a projectyes, when active
attachment_deleteDetach a policy attachment from a projectyes, when active
exportExport DLP settings, rules, policies and attachments as one YAML document
apply_dry_runPlan an org document against the org without changing anything
applyApply an org documentyes
approvals_listList pending and recent management approvals
approval_approveApprove an approval raised by a different principalyes
approval_rejectReject a pending approvalyes

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)​

ToolWhat it does
checkAsk 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.