MCP Server

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 as Model Context Protocol (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 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:

node -v   # should be v20.x or higher

If you need to install or update Node.js, visit nodejs.org or use nvm.

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 below for the verified configuration.

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

Claude Code (CLI)
Claude Code (.mcp.json)
Claude Desktop
VS Code Copilot

Remote (recommended):

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):

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:

claude mcp list

Add to .mcp.json in your project root:Remote (recommended):

{
  "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):

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

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

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.

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):

{
  "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:

echo "$HOME/.nvm/versions/node/$(node -v)/bin/npx"

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

{
  "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:

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

Windows: Run where npx in Command Prompt to find the correct path to npx.cmd on your system.

If you want to use the hosted remote server, use Claude Code or VS Code Copilot instead.

Add to .vscode/mcp.json (uses a different schema than other clients):Remote (recommended):

{
  "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):

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

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

Running locally? You can pass additional configuration via Optional Environment Variables — for example, LOG_LEVEL=debug for troubleshooting, or Kafka credentials to enable the direct Kafka tools.

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:

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.

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

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 for how to create them.

Keep your Client Secret safe. If compromised, delete the token from the API Tokens page and create a new one.

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 and 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:

echo "$HOME/.nvm/versions/node/$(node -v)/bin/npx"

Then use it as the command in your config. See the Claude Desktop tab 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 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 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

Agents — overview of all agent integration paths
CLI — command-line tool with agent-friendly JSON output and scripting support
API Reference — full REST API documentation

Getting Started

App

Troubleshooting

Deployment

Sources

Destinations

Transformation

Usage

Security

Developer Tools

Terraform

Prerequisites

Setup Modes

Setup

Verify Your Setup (Optional)

Available Tools

Optional: Direct Kafka Tools

Workflow Prompts

Real-Time Streaming (Remote Mode Only)

Authentication

Optional Environment Variables (Local Mode)

Troubleshooting

Log file locations

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

Common errors

Getting Started

App

Troubleshooting

Deployment

Sources

Destinations

Transformation

Usage

Security

Developer Tools

Terraform

Documentation Index

​Prerequisites

​Setup Modes

​Setup

​Verify Your Setup (Optional)

​Available Tools

​Optional: Direct Kafka Tools

​Workflow Prompts

​Real-Time Streaming (Remote Mode Only)

​Authentication

​Optional Environment Variables (Local Mode)

​Troubleshooting

​Log file locations

​macOS: nvm users — npx not found or wrong version

​Common errors

​Related

Prerequisites

Setup Modes

Setup

Verify Your Setup (Optional)

Available Tools

Optional: Direct Kafka Tools

Workflow Prompts

Real-Time Streaming (Remote Mode Only)

Authentication

Optional Environment Variables (Local Mode)

Troubleshooting

Log file locations

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

Common errors

Related