Skip to main content

MCP Integration

Enforce Control Zero policies on MCP tool calls across all MCP-compatible tools.

Overview​

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. Control Zero is built with MCP as a first-class integration point. Every MCP tool call can be governed by your policies before execution.

This integration covers all tools that support MCP servers, including:

  • Claude Code (Anthropic's CLI coding tool)
  • Cline (VS Code AI coding extension)
  • Cursor (AI-powered IDE)
  • Windsurf (AI-powered IDE by Codeium)
  • Any MCP-compatible client

How It Works​

Control Zero enforces policies on MCP tool calls using the mcp.tool.call action and mcp://{server}/{tool} resource URIs. The SDK evaluates each tool call against your policies before the tool executes.

Agent -> MCP Tool Call -> Control Zero Policy Check -> Tool Execution
                              |
                              v (if denied)
                         PolicyDeniedError

MCP Server Setup​

The Control Zero MCP server is published on npm as @controlzero/mcp-server and uses stdio transport.

Installation​

# Install globally
npm install -g @controlzero/mcp-server

# Or run directly without installing:
npx @controlzero/mcp-server

Environment Variables​

VariableRequiredDescription
CONTROLZERO_API_KEYYesYour Control Zero project API key

Client Configuration​

All clients launch the MCP server as a local stdio process.

Claude Code​

Add to .claude/settings.json:

{
  "mcpServers": {
    "controlzero": {
      "command": "controlzero-mcp",
      "env": {
        "CONTROLZERO_API_KEY": "cz_live_your_api_key_here"
      }
    }
  }
}

Claude Desktop​

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "controlzero": {
      "command": "controlzero-mcp",
      "env": {
        "CONTROLZERO_API_KEY": "cz_live_your_api_key_here"
      }
    }
  }
}

Cline​

Add the Control Zero MCP server through the Cline settings panel in VS Code:

  1. Open Cline settings.
  2. Navigate to the MCP Servers section.
  3. Add a new stdio server with command: controlzero-mcp and set CONTROLZERO_API_KEY in the environment.

Cursor​

Configure MCP servers in Cursor settings:

  1. Open Cursor settings (Cmd/Ctrl + ,).
  2. Search for "MCP" in the settings.
  3. Add a new stdio server with command controlzero-mcp and environment variable CONTROLZERO_API_KEY.

Windsurf​

Windsurf supports MCP servers through its configuration:

  1. Open Windsurf settings.
  2. Add the Control Zero MCP server with command controlzero-mcp and set CONTROLZERO_API_KEY in the environment.

SDK Integration​

Python​

from controlzero import Client

cz = Client(api_key="cz_live_your_api_key_here")

async def call_mcp_tool(server: str, tool: str, arguments: dict) -> dict:
    """Call an MCP tool with policy enforcement."""

    # Enforce the policy before calling the tool
    cz.guard(f"{server}/{tool}", args={"agent_id": "coding-agent", "arguments": str(arguments)})

    # Policy check passed. Call the tool
    return await mcp_client.callTool(server, tool, arguments)

Go​

func callMCPTool(ctx context.Context, server, tool string, args map[string]any) (any, error) {
    err := cz.Enforce(ctx, controlzero.CheckRequest{
        Action:   "mcp.tool.call",
        Resource: fmt.Sprintf("mcp://%s/%s", server, tool),
        Context: map[string]string{
            "agent_id": "coding-agent",
        },
    })
    if err != nil {
        return nil, err
    }

    return mcpClient.CallTool(ctx, server, tool, args)
}

Node.js​

function callMCPTool(server: string, tool: string, args: Record<string, any>) {
  cz.guard(server, { method: tool, args, raiseOnDeny: true });

  return mcpClient.callTool(server, tool, args);
}

Example Policy​

Control which MCP tools agents can use:

{
  "name": "mcp-tool-governance",
  "rules": [
    {
      "effect": "allow",
      "action": "mcp.tool.call",
      "resource": "mcp://filesystem/read_file"
    },
    {
      "effect": "allow",
      "action": "mcp.tool.call",
      "resource": "mcp://filesystem/list_directory"
    },
    {
      "effect": "deny",
      "action": "mcp.tool.call",
      "resource": "mcp://filesystem/write_file"
    },
    {
      "effect": "deny",
      "action": "mcp.tool.call",
      "resource": "mcp://shell/execute"
    },
    {
      "effect": "allow",
      "action": "mcp.tool.call",
      "resource": "mcp://database/read_query"
    },
    {
      "effect": "deny",
      "action": "mcp.tool.call",
      "resource": "mcp://database/write_query"
    }
  ]
}

This policy allows agents to read files and query databases, but blocks file writes and shell execution.

MCP Resource URI Format​

Control Zero uses a consistent URI format for MCP resources:

mcp://{server_name}/{tool_name}

Examples:

  • mcp://filesystem/read_file: Reading a file through the filesystem MCP server
  • mcp://github/create_issue: Creating a GitHub issue
  • mcp://database/execute_query: Running a database query
  • mcp://shell/execute: Executing a shell command
  • mcp://slack/send_message: Sending a Slack message

Next Steps​