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
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
claude mcp add --scope user streamkap \
-e STREAMKAP_CLIENT_ID=your-client-id \
-e STREAMKAP_CLIENT_SECRET=your-client-secret \
-- npx -y @streamkap/tools
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"
}
}
}
}
{
"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.
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"
}
}
}
}
echo "$HOME/.nvm/versions/node/$(node -v)/bin/npx"
{
"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"
}
}
}
}
/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"
}
}
}
}
{
"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
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.
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 |
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 |
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 |
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"
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
