> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamkap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect AI agents to Streamkap to manage CDC pipelines, sources, destinations, and transforms via natural language.

The Streamkap MCP Server lets AI agents interact with your Streamkap Change Data Capture (CDC) infrastructure using natural language. It wraps the [Streamkap REST API](/api-reference) as [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) tools that agents can call to monitor pipeline health, inspect sources, destinations, topics, and transforms, manage the full lifecycle of your resources, and troubleshoot issues through logs and metrics.

## Prerequisites

* A Streamkap account
* An API token (Client ID and Client Secret) — see [API Tokens](/api-tokens) for how to create one. **Both modes require these credentials** — "remote" only means the server itself is hosted, not that authentication is skipped.
* **Local mode only:** Node.js 20+

Check your Node.js version:

```bash theme={null}
node -v   # should be v20.x or higher
```

If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org) or use [nvm](https://github.com/nvm-sh/nvm).

<Warning>
  **macOS users with nvm + Claude Desktop:** Claude Desktop is a GUI app that does not source your shell profile (`~/.zshrc`, `~/.bashrc`), so it cannot find your nvm-managed Node.js. You must provide the absolute path to `npx` and set the `PATH` environment variable explicitly in your config — see the [Claude Desktop tab](#setup) below for the verified configuration.
</Warning>

## Setup Modes

The MCP server can run in two modes:

* **Remote (hosted, recommended):** Connect to the hosted server at `https://mcp.streamkap.com/mcp`. No local install required — credentials are passed as HTTP headers (`X-Streamkap-Client-ID` / `X-Streamkap-Client-Secret`). [Real-time topic streaming](#real-time-streaming-remote-mode-only) is only available in this mode.
* **Local (via npx):** Run the server locally as a child process with `npx -y @streamkap/tools`. Credentials are passed as environment variables. Requires Node.js 20+.

## Setup

<Tabs>
  <Tab title="Claude Code (CLI)">
    **Remote (recommended):**

    ```bash theme={null}
    claude mcp add --scope user \
      --header "X-Streamkap-Client-ID: your-client-id" \
      --header "X-Streamkap-Client-Secret: your-client-secret" \
      --transport http \
      streamkap https://mcp.streamkap.com/mcp
    ```

    **Local (via npx):**

    ```bash theme={null}
    claude mcp add --scope user streamkap \
      -e STREAMKAP_CLIENT_ID=your-client-id \
      -e STREAMKAP_CLIENT_SECRET=your-client-secret \
      -- npx -y @streamkap/tools
    ```

    **Verify the server is registered:**

    ```bash theme={null}
    claude mcp list
    ```
  </Tab>

  <Tab title="Claude Code (.mcp.json)">
    Add to `.mcp.json` in your project root:

    **Remote (recommended):**

    ```json theme={null}
    {
      "mcpServers": {
        "streamkap": {
          "type": "http",
          "url": "https://mcp.streamkap.com/mcp",
          "headers": {
            "X-Streamkap-Client-ID": "your-client-id",
            "X-Streamkap-Client-Secret": "your-client-secret"
          }
        }
      }
    }
    ```

    **Local (via npx):**

    ```json theme={null}
    {
      "mcpServers": {
        "streamkap": {
          "command": "npx",
          "args": ["-y", "@streamkap/tools"],
          "env": {
            "PATH": "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin",
            "STREAMKAP_CLIENT_ID": "your-client-id",
            "STREAMKAP_CLIENT_SECRET": "your-client-secret"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop currently supports Streamkap **only via local stdio mode** (remote header forwarding is unreliable across Claude Desktop builds). Add the entry to your config file:

    * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

    <Note>
      The `streamkap` entry must be nested inside the `mcpServers` object. Placing it at the root level of the config file will cause it to be silently ignored.
    </Note>

    **Local (via npx) — macOS with nvm:**

    Use the absolute path to your nvm-managed `npx`. Claude Desktop is a GUI app and does not source your shell profile, so it will not find `npx` on its own. Replace the version below with your installed Node.js version (`node -v`):

    ```json theme={null}
    {
      "mcpServers": {
        "streamkap": {
          "command": "/Users/<you>/.nvm/versions/node/v22.22.0/bin/npx",
          "args": ["-y", "@streamkap/tools"],
          "env": {
            "PATH": "/Users/<you>/.nvm/versions/node/v22.22.0/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin",
            "STREAMKAP_CLIENT_ID": "your-client-id",
            "STREAMKAP_CLIENT_SECRET": "your-client-secret"
          }
        }
      }
    }
    ```

    Find your absolute path with:

    ```bash theme={null}
    echo "$HOME/.nvm/versions/node/$(node -v)/bin/npx"
    ```

    **Local (via npx) — macOS without nvm (Homebrew):**

    ```json theme={null}
    {
      "mcpServers": {
        "streamkap": {
          "command": "/opt/homebrew/bin/npx",
          "args": ["-y", "@streamkap/tools"],
          "env": {
            "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
            "STREAMKAP_CLIENT_ID": "your-client-id",
            "STREAMKAP_CLIENT_SECRET": "your-client-secret"
          }
        }
      }
    }
    ```

    Use `/usr/local/bin/npx` instead on Intel Macs.

    **Local (via npx) — Windows:**

    ```json theme={null}
    {
      "mcpServers": {
        "streamkap": {
          "command": "C:\\Program Files\\nodejs\\npx.cmd",
          "args": ["-y", "@streamkap/tools"],
          "env": {
            "STREAMKAP_CLIENT_ID": "your-client-id",
            "STREAMKAP_CLIENT_SECRET": "your-client-secret"
          }
        }
      }
    }
    ```

    <Tip>
      **Windows:** Run `where npx` in Command Prompt to find the correct path to `npx.cmd` on your system.
    </Tip>

    <Note>
      If you want to use the hosted remote server, use Claude Code or VS Code Copilot instead.
    </Note>
  </Tab>

  <Tab title="VS Code Copilot">
    Add to `.vscode/mcp.json` (uses a different schema than other clients):

    **Remote (recommended):**

    ```json theme={null}
    {
      "servers": {
        "streamkap": {
          "type": "http",
          "url": "https://mcp.streamkap.com/mcp",
          "headers": {
            "X-Streamkap-Client-ID": "your-client-id",
            "X-Streamkap-Client-Secret": "your-client-secret"
          }
        }
      }
    }
    ```

    **Local (via npx):**

    ```json theme={null}
    {
      "servers": {
        "streamkap": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@streamkap/tools"],
          "env": {
            "PATH": "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin",
            "STREAMKAP_CLIENT_ID": "your-client-id",
            "STREAMKAP_CLIENT_SECRET": "your-client-secret"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Info>
  Using a different MCP-compatible client? Connect with the URL `https://mcp.streamkap.com/mcp` plus `X-Streamkap-Client-ID` / `X-Streamkap-Client-Secret` headers (remote), or run `npx -y @streamkap/tools` with the same values as environment variables (local).
</Info>

<Tip>
  Running locally? You can pass additional configuration via [Optional Environment Variables](#optional-environment-variables) — for example, `LOG_LEVEL=debug` for troubleshooting, or Kafka credentials to enable the direct Kafka tools.
</Tip>

## Verify Your Setup (Optional)

If things aren't working, the fastest way to check whether it's your credentials or your client config is to test the same credentials from the terminal using the [Streamkap CLI](/cli):

```bash theme={null}
npm install -g @streamkap/tools
export STREAMKAP_CLIENT_ID="your-client-id"
export STREAMKAP_CLIENT_SECRET="your-client-secret"
streamkap doctor
```

If `doctor` passes the credentials and API authentication checks, the same values will work in your MCP client. This step is optional but the fastest way to catch a bad credential before debugging your client config.

## Available Tools

Once connected, your agent has access to tools covering the full Streamkap API surface:

| Category             | What your agent can do                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Pipelines**        | List, create, update, delete, start, stop, restart, view metrics and logs, bulk operations                   |
| **Sources**          | Manage CDC connectors — deploy, pause, resume, restart, stop, snapshot, check status                         |
| **Destinations**     | Manage sinks — deploy, pause, resume, restart, stop, monitor throughput and lag                              |
| **Transforms**       | Create and manage stream processors, deploy to preview or production, run unit tests, inspect failed records |
| **Topics**           | List and inspect Kafka topics, read sample messages                                                          |
| **Tags**             | Organise and search resources by tag                                                                         |
| **Schema Registry**  | Browse subjects and schemas                                                                                  |
| **Consumer Groups**  | Inspect lag, identify stuck consumers, reset offsets                                                         |
| **Dashboard & Logs** | Organisation-wide stats, data lineage between sources and destinations, search and filter logs               |
| **Alerts**           | Manage notification subscribers and preferences                                                              |
| **Usage**            | Query and export usage metrics                                                                               |
| **Kafka Access**     | Manage direct-Kafka users (list, create, update, delete)                                                     |
| **Cluster Scaling**  | Inspect cluster status, scale up or down, track scaling operations                                           |
| **Admin**            | List services and switch between them                                                                        |

For the full list of API operations, see the [API Reference](/api-reference).

### Optional: Direct Kafka Tools

Two additional tools — `streamkap_consume_messages` and `streamkap_produce_message` — let agents interact with Kafka directly. They require Kafka credentials (bootstrap servers, username, password — all three together) from the [Kafka Access](/kafka-access) page. In local mode, set `KAFKA_BOOTSTRAP_SERVERS`, `KAFKA_API_KEY`, and `KAFKA_API_SECRET` as environment variables. Without Kafka credentials, agents can still read topic data via the REST-based `streamkap_get_topic_messages` tool.

## Workflow Prompts

The MCP server registers seven workflow prompts that surface as slash commands or prompt picks in most clients. Each prompt walks an agent through a structured operational task:

| Prompt                    | Purpose                                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| `troubleshoot-pipeline`   | Diagnose a specific pipeline (or all pipelines): health, metrics, logs, dead letter queue (DLQ) |
| `setup-pipeline`          | End-to-end guide for creating a new source → destination pipeline                               |
| `infrastructure-overview` | High-level health check across sources, destinations, pipelines, transforms                     |
| `diagnose-dlq-errors`     | Investigate dead letter queue topics and classify errors                                        |
| `report-pipeline-health`  | Generate a comprehensive pipeline health report with metrics and DLQ analysis                   |
| `deploy-monitoring-agent` | Set up monitoring across pipelines, sources, and destinations                                   |
| `triage-agent-error`      | Triage issues with any Streamkap entity using logs, metrics, and DLQ inspection                 |

These prompts appear in your client's prompt picker UI (or as slash commands in clients that support them — the exact format varies between clients).

## Real-Time Streaming (Remote Mode Only)

The hosted server exposes an SSE endpoint for real-time topic streaming at `https://mcp.streamkap.com/subscribe/<topic>`. Supports single topics, comma-separated lists, and regex patterns (`?pattern=source_.*`). Uses the same `X-Streamkap-Client-ID` / `X-Streamkap-Client-Secret` headers as MCP tool calls. Connect with any SSE client, `curl`, or from your application code.

Not available in local mode. For terminal-based real-time consumption, use [`streamkap kafka subscribe`](/cli#direct-kafka-access).

## Authentication

Streamkap handles token exchange and refresh automatically — you just provide your Client ID and Client Secret (as headers in remote mode, or environment variables in local mode). See [API Tokens](/api-tokens) for how to create them.

<Warning>
  Keep your Client Secret safe. If compromised, delete the token from the [API Tokens](/api-tokens) page and create a new one.
</Warning>

## Optional Environment Variables (Local Mode)

| Variable            | Description                                                                        |
| ------------------- | ---------------------------------------------------------------------------------- |
| `STREAMKAP_API_URL` | Override the API base URL (defaults to `https://api.streamkap.com`)                |
| `LOG_LEVEL`         | Server log verbosity: `trace`, `debug`, `info` (default), `warn`, `error`, `fatal` |

For Kafka and Schema Registry credentials, see [Direct Kafka Tools](#optional-direct-kafka-tools) and [Kafka Access](/kafka-access).

## Troubleshooting

### Log file locations

**Claude Desktop** (log file name matches the key in your `mcpServers` config):

* macOS: `~/Library/Logs/Claude/mcp-server-streamkap.log`
* Windows: `%APPDATA%\Claude\logs\mcp-server-streamkap.log`

### macOS: nvm users — `npx` not found or wrong version

Claude Desktop does not source your shell profile, so it cannot find nvm-managed Node.js. Find your absolute `npx` path:

```bash theme={null}
echo "$HOME/.nvm/versions/node/$(node -v)/bin/npx"
```

Then use it as the `command` in your config. See the [Claude Desktop tab](#setup) above for the full JSON example. **Homebrew users (no nvm):** use `/opt/homebrew/bin/npx` (Apple Silicon) or `/usr/local/bin/npx` (Intel).

### Common errors

| Symptom                                                                         | Likely cause                                                                                                          | Fix                                                                                                        |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `ERROR: You must supply a command`                                              | Old `npx` resolving via default PATH instead of Node 20+                                                              | Use the absolute path to `npx` from Node 20+ (see nvm section above)                                       |
| `Authentication failed` / 401 errors on every tool call                         | Missing or invalid Client ID / Secret                                                                                 | Verify your credentials in the [API Tokens](/api-tokens) dashboard, then run `streamkap doctor` to confirm |
| Server appears in client but tools fail silently                                | Credentials reached the server but are wrong for your tenant                                                          | Run `streamkap doctor` with the same credentials to surface the underlying error                           |
| Server connects then immediately disconnects                                    | Wrong Node version or package install failure                                                                         | Check the MCP log file for `npx` stderr output                                                             |
| Claude Desktop ignores the `streamkap` entry                                    | Entry placed at root of `claude_desktop_config.json` instead of inside `mcpServers`                                   | Move it inside the `mcpServers` object                                                                     |
| Claude Desktop fails to connect with `"type": "http"` or `"type": "sse"` config | Older config that tries to use remote MCP via `claude_desktop_config.json` (not currently reliable in Claude Desktop) | Switch to local stdio mode using the [Claude Desktop tab](#setup) above                                    |
| Need more detail in local mode                                                  | Default log level is `info`                                                                                           | Add `"LOG_LEVEL": "debug"` to the `env` block and re-check the log file                                    |

## Related

* [Agents](/agents) — overview of all agent integration paths
* [CLI](/cli) — command-line tool with agent-friendly JSON output and scripting support
* [API Reference](/api-reference) — full REST API documentation