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. The hosted server supports browser-based OAuth sign-in — no API keys to create.
For header-credential or local setups: an API token (Client ID and Client Secret — see API Tokens) or a Project Key.
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

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.
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 is available on the hosted server. 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.

Claude Code (CLI)
Claude Desktop
VS Code Copilot
Other clients

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.

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.

Add to .vscode/mcp.json — no credentials needed; VS Code prompts you to sign in on first use:

{
  "servers": {
    "streamkap": {
      "type": "http",
      "url": "https://mcp.streamkap.com/mcp"
    }
  }
}

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

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 or a Project Key.

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.

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

Remote (header credentials):

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

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

For the hosted server, connect Claude Desktop with OAuth sign-in. 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

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.

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

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

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.
API token — a Client ID and Client Secret, passed as headers in remote mode or environment variables in local mode. See API Tokens.
Project Key — a single bundled credential that also carries tool scoping. See Project Keys.

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

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

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

Optional Environment Variables (Local Mode)

Variable	Description
`STREAMKAP_PROJECT_KEY`	Base64-encoded Project Key — 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 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	Header-credential remote MCP via `claude_desktop_config.json` is not reliable in Claude Desktop	For the hosted server, connect via OAuth sign-in (Add custom connector); otherwise 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

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.

Claude Code (CLI)
VS Code Copilot
Other clients (mcpServers)

claude mcp add --scope user --transport http streamkap-docs https://docs.streamkap.com/mcp

Add to .vscode/mcp.json (VS Code uses the servers key):

{
  "servers": {
    "streamkap-docs": {
      "type": "http",
      "url": "https://docs.streamkap.com/mcp"
    }
  }
}

Cursor, Windsurf, and most other clients use the mcpServers key:

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

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

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

Restricting which tools an agent can use

Optional Environment Variables (Local Mode)

Troubleshooting

Log file locations

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

Common errors

Documentation MCP

​Prerequisites

​Setup Modes

​Sign in with OAuth (remote)

​Setup

​Verify Your Setup (Optional)

​Available Tools

​Optional: Direct Kafka Tools

​Workflow Prompts

​Real-Time Streaming (Remote Mode Only)

​Authentication

​Restricting which tools an agent can use

​Optional Environment Variables (Local Mode)

​Troubleshooting

​Log file locations

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

​Common errors

​Documentation MCP

​Related

Prerequisites

Setup Modes

Sign in with OAuth (remote)

Setup

Verify Your Setup (Optional)

Available Tools

Optional: Direct Kafka Tools

Workflow Prompts

Real-Time Streaming (Remote Mode Only)

Authentication

Restricting which tools an agent can use

Optional Environment Variables (Local Mode)

Troubleshooting

Log file locations

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

Common errors

Documentation MCP

Related