API Key Authentication

API keys let you connect to the CloudZero MCP server without browser-based sign-in. This is useful for automation, CI/CD pipelines, and MCP clients that do not support interactive OAuth flows.

Prerequisites

• A CloudZero account with permissions to create API keys
• An MCP client that supports custom HTTP headers

Step 1: Create an API key

1. Navigate to Settings > API Keys in the CloudZero application.

2. Select Create New API Key.

3. Enter a name and description for the key.

4. Under API Key Scopes, expand the Ai-Hub section and select mcp.

   

5. Select Create API Key.

6. Copy the API key immediately. It will not be shown again.

For detailed instructions, see Create a new API key.

⚠️

API keys are organization-level tokens. Anyone with the key has full access to all cost data in the associated organization. Treat API keys as secrets and do not commit them to version control.

Step 2: Configure your MCP client

Using .mcp.json

If your MCP client supports .mcp.json configuration (Claude Code, Cursor, VS Code, and others), add the following to your .mcp.json file:

{
  "mcpServers": {
    "cloudzero": {
      "type": "http",
      "url": "https://czca-server.discovery.cloudzero.com/mcp",
      "headers": {
        "X-Api-Key": "<your-api-key>"
      }
    }
  }
}

Replace <your-api-key> with the API key you created in step 1.

ℹ️

The .mcp.json file is typically located in your project root or home directory, depending on the client. Check your client's documentation for the exact location.

After npx add-mcp installation

If you installed the MCP server using npx add-mcp from the manual installation page, add the headers block to the existing server entry in your client's MCP configuration file:

Add the "headers" object to the existing server entry:

"headers": {
  "X-Api-Key": "<your-api-key>"
}

Using an environment variable

To avoid storing your API key directly in configuration files, reference an environment variable instead:

{
  "mcpServers": {
    "cloudzero": {
      "type": "http",
      "url": "https://czca-server.discovery.cloudzero.com/mcp",
      "headers": {
        "X-Api-Key": "${CLOUDZERO_API_KEY}"
      }
    }
  }
}

Then set the environment variable in your shell or CI/CD environment:

export CLOUDZERO_API_KEY="your-api-key-here"

⚠️

Do not commit API keys to version control. Use environment variables or a secrets manager for shared configurations.

Authentication behavior

The MCP server checks for authentication in the following order:

1. API key — If an X-Api-Key header is present, the server validates the key. OAuth is not checked.
2. OAuth — If no API key header is present, the server uses the OAuth bearer token from the browser-based sign-in flow.

You do not need to remove OAuth configuration when adding an API key. The X-Api-Key header takes precedence when both are present.

API key vs OAuth

For details on daily usage quotas and what happens when the limit is reached, see Usage quotas.