@controlzero/mcp-server

Control Zero MCP server for AI agent integration. Exposes the Control Zero REST API as Model Context Protocol tools, enabling AI coding clients to manage governance policies, projects, API keys, audit logs, and more.

Prerequisites

• Node.js 18+
• A Control Zero API key (cz_live_* or cz_test_* prefix)

Available Tools

| Tool | Description | | ------------------------- | ------------------------------------- | | list_policies | List policies for a project | | get_policy | Get policy details by ID | | create_policy | Create a new governance policy | | update_policy | Update an existing policy | | delete_policy | Delete a policy | | toggle_policy | Enable/disable a policy | | list_projects | List all projects in an organization | | get_project | Get project details | | create_project | Create a new project | | list_api_keys | List API keys for a project | | create_api_key | Create a new API key | | revoke_api_key | Revoke an API key | | query_audit_logs | Query audit logs with filters | | get_audit_stats | Get audit statistics | | get_governance_status | Get governance status for a project | | get_enforcement_stats | Get enforcement statistics | | toggle_governance | Enable/disable governance enforcement | | list_blueprints | List available policy blueprints | | deploy_blueprint | Deploy a blueprint to a project | | guard_check_tool_call | Advisory DLP check before a tool call | | guard_test_pattern | Test a candidate DLP regex | | guard_list_active_rules | List the org's live DLP rules |

Guard tools are advisory, not hard enforcement

The guard_* tools (guard_check_tool_call, guard_test_pattern, guard_list_active_rules) are cooperative: the MCP server returns a decision the caller is expected to honor, but the MCP server has no way to force the client to stop. An AI client that ignores a deny response can still run the tool.

For hard enforcement, use:

• The Control Zero SDK (@controlzero/sdk), which runs in-process and raises / denies before the tool fires.
• The Control Zero Gateway, which sits between your app and the LLM and blocks requests at the network boundary.

The guard tools exist so AI agents can be good citizens on machines where no SDK or Gateway is in front of every call. Pair them with the SDK or Gateway when compliance requires a hard gate.

Every guard decision carries a reason_code from the canonical Control Zero reason-code enum: NO_RULE_MATCH when nothing matched (advisory allow), RULE_MATCH when a mask or detect DLP rule fired (advisory warn), DLP_BLOCKED when a block rule fired (advisory deny).

Environment Variables

| Variable | Required | Default | Description | | --------------------- | -------- | ----------------------------------- | --------------------------------------- | | CONTROLZERO_API_KEY | Yes | -- | CZ API key (cz_live_* or cz_test_*) | | CONTROLZERO_API_URL | No | https://api.controlzero.ai/api/v1 | Base URL of the Control Zero API |

Client Setup

All clients use the same configuration pattern. Set your API key and optionally override the API URL.

1. Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

2. Claude Code

claude mcp add controlzero -- npx @controlzero/mcp-server

Then set the environment variable in your shell profile:

export CONTROLZERO_API_KEY="cz_live_your_key_here"

Or add it to your project's .claude/settings.json:

{
  "env": {
    "CONTROLZERO_API_KEY": "cz_live_your_key_here"
  }
}

3. Cursor

Edit ~/.cursor/mcp.json:

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

4. Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

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

5. VS Code Copilot

Edit your VS Code settings.json (Cmd+Shift+P > "Preferences: Open User Settings (JSON)"):

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

6. Gemini CLI

Edit ~/.gemini/settings.json:

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

7. Cline

Edit .cline/mcp_settings.json in your project root:

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

8. JetBrains (MCP Plugin)

Install the MCP plugin from the JetBrains Marketplace, then add to your MCP plugin settings:

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

Development

Build and run locally:

cd services/mcp-server
npm install
npm run dev

Run tests:

npm test

Build for production:

npm run build
npm start

Hosted mode (HTTP transport)

The same source ships two binaries:

• controlzero-mcp -- stdio transport, for desktop AI clients (Claude Desktop, Claude Code, Cursor, Windsurf, etc).
• controlzero-mcp-hosted -- HTTP transport, for AI clients that prefer a remote MCP endpoint and for embedding the MCP surface in your own app.

Hosted mode listens for JSON-RPC over HTTP and Server-Sent Events:

| Endpoint | Method | Auth | Purpose | | ---------- | ------ | ------ | ------------------------------------------------------------------- | | /health | GET | none | Liveness probe | | /metrics | GET | none | Prometheus exposition (request counters) | | /mcp | POST | bearer | Streamable HTTP JSON-RPC (initialize, tools/list, tools/call, ping) | | /mcp | GET | bearer | SSE stream (Accept: text/event-stream) |

Authentication is Authorization: Bearer cz_live_* (or cz_test_*). Each inbound request validates the bearer token against POST /v1/sdk/init and runs the rest of the request inside an AsyncLocalStorage-scoped context so concurrent requests with different keys stay isolated.

Run locally:

npm run dev:hosted
# or after build:
npm run start:hosted

Container image (production):

# Built and pushed by .github/workflows/publish-mcp-server.yml on
# every mcp-server-v* tag.
docker pull ghcr.io/maruthiprithivi/cz-mcp-server:latest
docker run --rm -p 8100:8100 \
  -e CONTROLZERO_API_URL=https://api.controlzero.ai/api/v1 \
  ghcr.io/maruthiprithivi/cz-mcp-server:latest

The production deployment routes mcp.controlzero.ai to this service via the production reverse proxy. See docker-compose.production.yml (mcp-server) for the deployment topology.

License

Proprietary. Copyright Control Zero.