MCP Server

This page describes the WarpStream Console MCP (Model Context Protocol) server for IDEs and AI assistants.

The WarpStream Console exposes an MCP endpoint over HTTP. Any MCP-capable client (for example Cursor, Claude Desktop, Claude Code, or Windsurf) can call the same control plane APIs the Console uses: listing virtual clusters and topics, inspecting diagnostics, querying Events, checking ACLs and pipelines, and similar.

You type questions in plain language; your client picks the tools the server exposes. For example:

• "Is anything wrong with my cluster?"

• "What topics are on this cluster?"

• "Who's getting ACL denials in the last hour?"

• "Show agent or pipeline errors since yesterday."

• "Is my consumer group falling behind?"

You do not need to know API routes—the MCP server tells the client what it supports.

The endpoint URL is:

https://console.warpstream.com/api/v1/mcp

Prerequisites

You need Events enabled on a virtual cluster before you can search event streams (agent logs, ACL logs, pipeline logs, and related types) through MCP or the Console.

Setup

Generate configuration in the Console

The simplest path is to use the configuration the Console generates for you:

1. Navigate to the WarpStream Console.

2. Open MCP in the left sidebar, or go directly to console.warpstream.com/mcp.

3. Choose which workspace(s) MCP should be able to reach.

4. Click Generate configuration and copy the snippet into your MCP client.

That snippet includes read-only API keys scoped to the workspaces you selected. Creating or rotating this configuration requires an admin on the workspace. For background on workspaces, roles, and grants, see Workspaces and access controls.

The JSON examples in the sections below are useful when you are merging configs by hand or adapting an example; they mirror what the generator produces.

Include the documentation MCP

Point your client at two HTTP MCP servers: the WarpStream cluster endpoint above, and the GitBook MCP endpoint for this documentation set, so the assistant can look up product behavior while it works.

• WarpStream cluster tools: https://console.warpstream.com/api/v1/mcp

• WarpStream documentation (GitBook MCP): https://docs.warpstream.com/warpstream/~gitbook/mcp

Cursor

Add the following to .cursor/mcp.json in your project or global Cursor settings. The first example is a single workspace; the second shows two workspaces with two headers.

{
  "mcpServers": {
    "warpstream": {
      "url": "https://console.warpstream.com/api/v1/mcp",
      "headers": {
        "warpstream-api-key-wi_aaaaaaaa_bbbb_4ccc_dddd_eeeeeeeeeeee": "<key-from-console>"
      }
    },
    "warpstream-docs": {
      "url": "https://docs.warpstream.com/warpstream/~gitbook/mcp"
    }
  }
}

{
  "mcpServers": {
    "warpstream": {
      "url": "https://console.warpstream.com/api/v1/mcp",
      "headers": {
        "warpstream-api-key-wi_aaaaaaaa_bbbb_4ccc_dddd_eeeeeeeeeeee": "<key-for-workspace-a>",
        "warpstream-api-key-wi_bbbbbbbb_cccc_4ddd_eeee_ffffffffffff": "<key-for-workspace-b>"
      }
    },
    "warpstream-docs": {
      "url": "https://docs.warpstream.com/warpstream/~gitbook/mcp"
    }
  }
}

Claude Desktop

Use the same JSON structure as Cursor. Place it in your Claude Desktop configuration file (claude_desktop_config.json).

Claude Code (CLI)

claude mcp add --transport http warpstream \
  https://console.warpstream.com/api/v1/mcp \
  --header "warpstream-api-key-wi_aaaaaaaa_bbbb_4ccc_dddd_eeeeeeeeeeee: <key-from-console>"

claude mcp add --transport http warpstream-docs \
  https://docs.warpstream.com/warpstream/~gitbook/mcp

Windsurf

Windsurf expects serverUrl instead of url for HTTP MCP servers:

{
  "mcpServers": {
    "warpstream": {
      "serverUrl": "https://console.warpstream.com/api/v1/mcp",
      "headers": {
        "warpstream-api-key-wi_aaaaaaaa_bbbb_4ccc_dddd_eeeeeeeeeeee": "<key-from-console>"
      }
    },
    "warpstream-docs": {
      "serverUrl": "https://docs.warpstream.com/warpstream/~gitbook/mcp"
    }
  }
}

Use workspace-scoped headers or a single warpstream-api-key header, not both in the same client configuration. When you use the MCP page in the Console, prefer the workspace-scoped headers it prints.

Workspace API key headers

If you edit configuration by hand, each workspace is authorized through its own HTTP header:

warpstream-api-key-<workspace_id>

The header name and the key value must match what the generated configuration from the Console would use.

Scope

What you can call depends on your API key and workspace access. Not every Console screen has a matching MCP tool yet. The tools your client shows are returned by the server at connect time and change as WarpStream extends the MCP surface.

For event payloads, fields, and query language details, see Events.

Troubleshooting

Events are disabled

Event-backed queries require Events on the cluster. See Enabling events.

401 or invalid API key

Confirm the key is still valid and that header names match the workspace IDs from the generated snippet.

Authentication

Pass API keys in HTTP headers. Keys issued from the MCP setup flow are read-only. You may also use an existing Console API Key if it has read access to the resources you need; use the same header names the configuration generator would produce for those workspaces. Authorization still follows your account’s workspace and role grants.