# MCP Server

The WarpStream Console exposes an [MCP](https://modelcontextprotocol.io/) 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](https://docs.warpstream.com/warpstream/reference/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](https://docs.warpstream.com/warpstream/reference/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

{% embed url="<https://vimeo.com/1183554951>" fullWidth="false" %}

### Generate configuration in the Console

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

1. Navigate to the [WarpStream Console](https://console.warpstream.com).
2. Open **MCP** in the left sidebar, or go directly to [console.warpstream.com/mcp](https://console.warpstream.com/mcp).
3. Choose which [workspace(s)](https://docs.warpstream.com/warpstream/reference/manage-console-access/workspaces-and-access-controls) 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](https://docs.warpstream.com/warpstream/reference/manage-console-access/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.

```json
{
  "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"
    }
  }
}
```

```json
{
  "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)

```bash
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:

```json
{
  "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"
    }
  }
}
```

{% hint style="warning" %}
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.
{% endhint %}

### 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](https://docs.warpstream.com/warpstream/reference/manage-console-access/workspaces-and-access-controls). 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](https://docs.warpstream.com/warpstream/reference/events).

## Troubleshooting

**Events are disabled**

Event-backed queries require [Events](https://docs.warpstream.com/warpstream/reference/events) on the cluster. See [Enabling events](https://docs.warpstream.com/warpstream/events#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](https://docs.warpstream.com/warpstream/reference/manage-console-access/workspaces-and-access-controls).