> ## 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.

# Streamkap MCP Server for AI agents

> Connect Claude, VS Code Copilot, and other MCP clients to Streamkap with OAuth sign-in or API tokens to manage CDC pipelines 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/authentication/access-token) 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. The hosted server supports browser-based [OAuth sign-in](#sign-in-with-oauth-remote) — no API keys to create.
* **For header-credential or local setups:** an API token (Client ID and Client Secret — see [API Tokens](/api-tokens)) or a [Project Key](/project-keys).
* **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

You can connect in three ways:

* **Remote — OAuth sign-in (recommended):** Connect to the hosted server at `https://mcp.streamkap.com/mcp` and authorize with your Streamkap account in the browser. No local install, no API keys to create or store. See [Sign in with OAuth](#sign-in-with-oauth-remote).
* **Remote — header credentials:** Connect to the same hosted URL and pass an API token as HTTP headers (`X-Streamkap-Client-ID` / `X-Streamkap-Client-Secret`). Best for headless and CI clients that can set headers but can't complete a browser sign-in.
* **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+.

[Real-time topic streaming](#real-time-streaming-remote-mode-only) is available on the hosted server.

## Sign in with OAuth (remote)

The hosted server is an OAuth 2.1 provider, so most MCP clients can connect with a browser sign-in instead of API keys. Point your client at `https://mcp.streamkap.com/mcp` with no credentials; on first connect it opens a browser where you sign in to Streamkap and authorize access. Your client stores and refreshes the tokens automatically.

<Tabs>
  <Tab title="Claude Code (CLI)">
    ```bash theme={null}
    claude mcp add --scope user --transport http streamkap https://mcp.streamkap.com/mcp
    ```

    Then run `/mcp` inside Claude Code and choose **Authenticate** for the `streamkap` server to complete sign-in in your browser. The `--scope user` flag registers the server for every project, not just the current directory.
  </Tab>

  <Tab title="Claude Desktop">
    Open **Settings → Connectors → Add custom connector**, enter the URL `https://mcp.streamkap.com/mcp`, then click **Connect** and sign in. This is the recommended way to use the hosted server with Claude Desktop.
  </Tab>

  <Tab title="VS Code Copilot">
    Add to `.vscode/mcp.json` — no credentials needed; VS Code prompts you to sign in on first use:

    ```json theme={null}
    {
      "servers": {
        "streamkap": {
          "type": "http",
          "url": "https://mcp.streamkap.com/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Any client that supports remote MCP servers with OAuth can connect to `https://mcp.streamkap.com/mcp` with no credentials and will prompt for sign-in. If your client can't complete a browser flow, use [header credentials](#setup) instead.
  </Tab>
</Tabs>

<Info>
  OAuth sign-in grants a curated set of tools: agents can read, create, update, and operate your resources, but **destructive actions are blocked** — they can't delete resources or reset connectors. For unrestricted access or custom tool scoping, use [header credentials](#setup) or a [Project Key](/project-keys#step-3-mcp-scoping).
</Info>

## Setup

The tabs below cover the **header-credential** (remote) and **local (npx)** setups. To connect with a browser sign-in instead, see [Sign in with OAuth](#sign-in-with-oauth-remote).

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

    ```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 (header credentials):**

    ```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">
    For the hosted server, connect Claude Desktop with [OAuth sign-in](#sign-in-with-oauth-remote). Header-credential forwarding via `claude_desktop_config.json` is unreliable across Claude Desktop builds, so for **header-credential** setups use local stdio mode instead — 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>
  </Tab>

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

    **Remote (header credentials):**

    ```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/authentication/access-token).

### 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

The MCP server accepts three credentials:

* **OAuth sign-in** (hosted server) — authorize with your Streamkap account in the browser; no keys to manage. See [Sign in with OAuth](#sign-in-with-oauth-remote).
* **API token** — a Client ID and Client Secret, passed as headers in remote mode or environment variables in local mode. See [API Tokens](/api-tokens).
* **Project Key** — a single bundled credential that also carries [tool scoping](/project-keys#step-3-mcp-scoping). See [Project Keys](/project-keys).

For API tokens and Project Keys, Streamkap handles token exchange and refresh automatically.

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

### Restricting which tools an agent can use

By default an agent can call every tool its credential is allowed. To narrow that surface:

* **Project Key (recommended):** set a tool profile and allow/block lists when you create the key — scoping is enforced server-side and can't be tampered with client-side. See [MCP scoping](/project-keys#step-3-mcp-scoping).
* **Headers (remote) or environment variables (local):** set `X-Streamkap-Tool-Profile` / `MCP_TOOL_PROFILE`, `X-Streamkap-Allow-Tools` / `MCP_ALLOW_TOOLS`, or `X-Streamkap-Block-Tools` / `MCP_BLOCK_TOOLS`. Allow lists win over block lists, which win over the profile.
* **OAuth sign-in:** uses a fixed curated profile that blocks destructive actions — see [Sign in with OAuth](#sign-in-with-oauth-remote).

## Optional Environment Variables (Local Mode)

| Variable                              | Description                                                                                                             |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `STREAMKAP_PROJECT_KEY`               | Base64-encoded [Project Key](/project-keys) — bundles API credentials, Kafka access, and tool scoping in a single value |
| `STREAMKAP_API_URL`                   | Override the API base URL (defaults to `https://api.streamkap.com`)                                                     |
| `MCP_TOOL_PROFILE`                    | Restrict the agent to a tool profile: `read-only`, `agent-operator`, `infra-admin`, or `full`                           |
| `MCP_ALLOW_TOOLS` / `MCP_BLOCK_TOOLS` | Comma-separated tool allow/block lists. Allow wins over block, which wins over the profile                              |
| `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 | Header-credential remote MCP via `claude_desktop_config.json` is not reliable in Claude Desktop | For the hosted server, connect via [OAuth sign-in](#sign-in-with-oauth-remote) (Add custom connector); otherwise 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                                                                                                                  |

## Documentation MCP

The Streamkap docs site runs its own MCP server at `https://docs.streamkap.com/mcp`. It is **separate** from the API server above and carries **no credentials** — it lets an agent search and read the Streamkap documentation (connector configs, how-tos, API reference) while it works. Add it alongside the `streamkap` server so your agent can look something up and act on it in the same session.

<Tabs>
  <Tab title="Claude Code (CLI)">
    ```bash theme={null}
    claude mcp add --scope user --transport http streamkap-docs https://docs.streamkap.com/mcp
    ```
  </Tab>

  <Tab title="VS Code Copilot">
    Add to `.vscode/mcp.json` (VS Code uses the `servers` key):

    ```json theme={null}
    {
      "servers": {
        "streamkap-docs": {
          "type": "http",
          "url": "https://docs.streamkap.com/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients (mcpServers)">
    Cursor, Windsurf, and most other clients use the `mcpServers` key:

    ```json theme={null}
    {
      "mcpServers": {
        "streamkap-docs": {
          "type": "http",
          "url": "https://docs.streamkap.com/mcp"
        }
      }
    }
    ```

    In Claude Desktop, add it as a custom connector instead: **Settings → Connectors → Add custom connector**, then enter `https://docs.streamkap.com/mcp`.
  </Tab>
</Tabs>

<Info>
  The docs MCP serves public documentation only — no sign-in, and it cannot read or change your infrastructure. To manage resources, use the [Streamkap MCP Server](#sign-in-with-oauth-remote) above.
</Info>

## 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/authentication/access-token) — full REST API documentation