The Cast AI Model Context Protocol (MCP) server enables AI-powered code editors like Cursor and Windsurf, plus general-purpose tools like Claude Desktop, to interact directly with the Cast AI API.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI applications to securely access external data sources and tools. The Cast AI MCP server provides AI agents with:

• Direct API access to Cast AI functionality
• Real-time data from your Cast AI account
• Code generation assistance for Cast AI integrations

Cast AI MCP server setup

Cast AI hosts a remote MCP server at https://docs.cast.ai/mcp. Configure your AI development tools to connect to this server.

{
  "mcpServers": {
    "castai": {
      "url": "https://docs.cast.ai/mcp",
      "headers": {
        "X-API-Key": "<your-cast-ai-api-key>",
        "x-readme-auth": "castai-mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "castai": {
      "url": "https://docs.cast.ai/mcp",
      "headers": {
        "Authorization": "Bearer <your-cast-ai-api-key>",
        "x-readme-auth": "castai-mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "castai": {
      "url": "https://docs.cast.ai/mcp",
      "headers": {
        "X-API-Key": "<your-cast-ai-api-key>",
        "x-readme-auth": "castai-mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "castai": {
      "url": "https://docs.cast.ai/mcp",
      "headers": {
        "Authorization": "Bearer <your-cast-ai-api-key>",
        "x-readme-auth": "castai-mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "castai": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://docs.cast.ai/mcp",
        "--header",
        "X-API-Key:<your-cast-ai-api-key>",
        "--header",
        "x-readme-auth:castai-mcp"
      ]
    }
  }
}

Authentication

The Cast AI MCP server requires two headers on every request:

Both headers are required. Requests missing either header will be rejected.

Cast AI API key

Two formats are supported for passing your Cast AI API key:

Both formats use the same Cast AI API key and provide identical access. Use whichever format your tooling or organization requires. Expired tokens require a manual config update, so long-lived API keys are recommended.

MCP server authentication

All requests must include x-readme-auth: castai-mcp in addition to your Cast AI API key. This fixed value is a protocol-level signal that tells the MCP server to advertise authentication support to AI agent platforms that require it before they will connect, including AWS DevOps Agent and others.

See the configuration examples above for how to add this header to your client. If your client supports only one header, sends a single header, or would place Cast AI credentials somewhere they could be exposed, see Single-header configuration.

Single-header configuration

Use this configuration when a client supports only one authentication header, sends a single header, or routes the endpoint through a field where placing your Cast AI API key could expose it (for example, a URL that appears in logs). AWS DevOps Agent is one such client.

In these cases, keep your Cast AI API key in the header and pass the x-readme-auth value in the query string using the token parameter. Configure the client with:

• Endpoint URL: https://docs.cast.ai/mcp?token=castai-mcp
• Authentication header: X-API-Key: <your-cast-ai-api-key>

This keeps your API key in the header, so it is never placed in the URL. The value moved to the query string is the fixed castai-mcp signal, which is publicly documented and grants no access on its own.

Obtaining an API key

Generate an API access key from the Cast AI console under User > API keys. For details, see Authentication.

Testing your MCP setup

Once configured, test your MCP server connection:

1. Open your AI editor (Cursor, Windsurf, etc.)
2. Start a new chat with the AI assistant
3. Ask about Cast AI — try a prompt like:
   • "List my Cast AI clusters."

The AI should now have access to your Cast AI account data through the MCP server.

Troubleshooting

If the MCP server is not responding or returning errors, check the MCP server logs for your client before investigating further.

tail -f ~/Library/Logs/Claude/mcp*.log

After reviewing logs, also verify that:

• Your API key is valid and has not been deleted or disabled
• The header value in your config does not include extra spaces or line breaks
• Both X-API-Key (or Authorization) and x-readme-auth: castai-mcp are present in your configuration
• For Claude Desktop: --header values must have no space after the colon (use X-API-Key:<key> and x-readme-auth:castai-mcp, not x-readme-auth: castai-mcp)
• You fully quit and relaunched your AI editor after updating the config file — most clients do not reload the MCP configuration without a restart