Hosted MCP Server

Status: COMING SOON

The local MCP server is available now on all tiers. It exposes the management tools and the cooperative check tool through stdio.

Hosted endpoint is COMING SOON

The managed mcp.controlzero.ai endpoint is not live. This page documents the planned HTTP offering; use the local MCP server today.

The Hosted MCP Server will be a cloud-hosted version of the Control Zero MCP server that runs as an HTTP service. Any MCP-capable AI coding client will be able to connect to it via the Streamable HTTP transport protocol -- no local installation required.

Hosted vs Local

For the local (stdio) option, 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.

Feature	Local (stdio)	Hosted (HTTP)
Transport	stdio	Streamable HTTP
Installation	npm install -g @controlzero/mcp-server	None (cloud-hosted)
Availability	All tiers	Entitlement-gated (COMING SOON)
Network	Runs on your machine	Runs on Control Zero infrastructure
Authentication	CONTROLZERO_MGMT_KEY / CONTROLZERO_API_KEY	Authorization: Bearer with either key
Tools	Management tools and check	The same tools

Both run the same server code and expose the same tools; see Available Tools.

Provisioning

Via Dashboard

1. Go to Integrations > MCP Server in the Control Zero dashboard
2. In the Hosted MCP Server section, click Provision Hosted MCP
3. The connection URL and client configuration snippets will appear
4. Copy the configuration for your IDE

Via API

POST /api/projects/{projectID}/mcp/provision
Cookie: cz_session=<your dashboard session cookie>

Returns:

{
  "status": "provisioned",
  "mcp_url": "https://mcp.controlzero.ai/mcp",
  "transport": "streamable-http",
  "provisioned_at": "2026-04-11T10:00:00Z",
  "instructions": "..."
}

Check Status

GET /api/projects/{projectID}/mcp/status

Deprovision

DELETE /api/projects/{projectID}/mcp/deprovision

Client Configuration

Send one key as the bearer token. A management key (cz_mgmt_*) reaches the management tools; an enforcement key (cz_live_* or cz_test_*) reaches check. A tool called with the other kind of key returns an error naming the key it needs.

Claude Desktop

Add to your Claude Desktop MCP configuration file:

{
  "mcpServers": {
    "controlzero": {
      "url": "https://mcp.controlzero.ai/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer cz_live_YOUR_API_KEY"
      }
    }
  }
}

Cursor

Add to Cursor's MCP settings:

{
  "mcpServers": {
    "controlzero": {
      "url": "https://mcp.controlzero.ai/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer cz_live_YOUR_API_KEY"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to VS Code settings JSON:

{
  "mcp": {
    "servers": {
      "controlzero": {
        "url": "https://mcp.controlzero.ai/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer cz_live_YOUR_API_KEY"
        }
      }
    }
  }
}

Windsurf / Cline / JetBrains

These clients support the Streamable HTTP transport. Use the same URL and headers pattern as above -- consult each client's documentation for the exact configuration file location.

Security Model (planned)

This section describes the hosted service as built; none of it is live until the managed endpoint ships.

• Authentication on every request. Each request carries its own bearer key, validated against the API before any tool runs: a management key at GET /v1/management/self, an enforcement key at GET /v1/sdk/bootstrap. Concurrent requests with different keys are isolated, and there is no session state.
• Scope comes from the key. A tool acts with the permissions of the key that called it, and a publish-class change made with a management key still needs a second principal.
• No browser access. The endpoint sends no CORS headers; it is for machine-to-machine MCP clients.
• TLS only, behind a managed reverse proxy.

AI Client -> HTTPS -> mcp.controlzero.ai -> Control Zero API -> Response

The hosted server translates between MCP and the Control Zero API and stores nothing itself. Management changes made through it are audited by the API, as for any other client, and attributed to the MCP source.

Troubleshooting (once live)

401 on every request

• Send Authorization: Bearer <key> with a cz_mgmt_, cz_live_ or cz_test_ key.
• Verify the key has not been revoked in the dashboard.

A tool returns "requires a management key" or "requires an enforcement key"

The bearer key is the wrong kind for that tool. Management tools need cz_mgmt_*; check needs cz_live_* or cz_test_*.

"Method not found"

• Ensure your MCP client is using the Streamable HTTP transport, not stdio
• Verify the URL ends with /mcp (not /mcp/ with trailing slash)