StreamWright MCP server
The StreamWright MCP server lets an AI assistant look up your installed connectors, read their contracts and guides, and check the sources and jobs it writes. It works with any client that speaks the Model Context Protocol (MCP), such as GitHub Copilot, Claude Code, Claude Desktop, Cursor, Google Antigravity, Zed or Windsurf.
pip install streamwright-mcp, then add the streamwright-mcp command to your assistant. It runs locally by default,
never runs a source or a job, and never reads secret values.
Install
pip install streamwright-mcp # or: uv pip install streamwright-mcp
streamwright-mcp --help # also available as: sw mcp --help
From a local clone: pip install -e /path/to/streamwright-mcp.
Connect your assistant
Most assistants start the server themselves, as a local process that talks over standard input/output (stdio,
the default). Pick yours below.
GitHub Copilot CLI
copilot mcp add streamwright -- streamwright-mcp
Claude Code
claude mcp add streamwright -- streamwright-mcp
VS Code (GitHub Copilot)
{
"servers": {
"streamwright": {
"type": "stdio",
"command": "streamwright-mcp"
}
}
}
Claude Desktop, Cursor and Google Antigravity
These use the same mcpServers block:
{
"mcpServers": {
"streamwright": {
"command": "streamwright-mcp",
"args": ["--transport", "stdio"]
}
}
}
| Client | Configuration file |
|---|---|
| Claude Desktop | macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json; Linux: ~/.config/Claude/claude_desktop_config.json |
| Cursor | .cursor/mcp.json in your workspace root |
| Google Antigravity | ~/.gemini/config/mcp_config.json |
Other clients, and where the command lives
Any other MCP client (Zed, Windsurf, ...) needs the same command: streamwright-mcp.
- If
streamwright-mcpis not on yourPATH, use its full path, for example/path/to/venv/bin/streamwright-mcp(which streamwright-mcpprints it;where streamwright-mcpon Windows). - To run it without installing, use
"command": "uvx"with"args": ["streamwright-mcp", "--transport", "stdio"].
Tools
The tools fall into three groups: find things, read a guide or schema, and check your YAML. An argument ending in
? is optional.
Find
| Tool | What it does |
|---|---|
list_connectors | The installed connectors and the engines each supports, without importing them. With include_hub, also the Hub connectors you can install.Takes: include_hub?, engine? |
search_docs | Keyword search over the engine guides, the connector guides and the CLI help. snake_case and dotted names match whole. Returns the 10 best sections, each with a snippet and the tool call that opens it.Takes: query |
Read
| Tool | What it does |
|---|---|
get_connector_contract | A connector's keys (connection, sign-in, secrets), its operations and query builders, and what differs per engine. Operations are summarised; operation returns one in full. For a connector that is not installed: how to install it.Takes: name, engine?, operation? |
get_connector_guide | A connector's guide: examples, query builders (such as Google Ads gaql), vendor arguments, engine notes. Without section, the section titles.Takes: name, section? |
describe_connector_type | A vendor type of an SDK connector (Microsoft Ads, Meta Ads, Google Ads), read offline from its installed library: an enum's values in their exact case, or an object's fields and their types. REST connectors have none: their guides list the values. Takes: name, type_name |
get_engine_guide | An engine's guide, for example DuckDBJob. Without section, the section titles.Takes: kind, section? |
get_core_schema | The JSON Schemas (draft 7): an index, one schema's outline (kind), or one definition or dotted path such as steps.sql (section).Takes: kind?, section? |
get_cli_reference | Live help for a streamwright (sw) command, read from the CLI, for example run or duckdb state. Without command, the command list.Takes: command? |
Check
| Tool | What it does |
|---|---|
validate_source_config | Checks a source folder as streamwright validate does, with file:line diagnostics. A job file is checked by its engine.Takes: source_dir, strict? |
inspect_stream_transform | Shows how one stream is planned: its requests, the tables and columns each step reads, and its exports' primary-key check. Takes: source_dir, stream_name |
validate_duckdb_job, validate_spark_job | One tool per installed job engine. Checks a job offline, with no credentials. config gives input values as --set does; analyze adds the execution plan, as streamwright plan prints it.Takes: content or path, config?, overlays?, strict?, analyze? |
Good to know:
- Paths must be inside the allowed folders (
--root, below). URLs such ass3://are refused. - Inline
contentis limited to 5 MiB. - A result over 20,000 characters is shortened and marked
"truncated": truewith ahint. Narrow the request withoperation,sectionorsearch_docs.
Resources
For clients that can attach MCP resources:
| URI | Content |
|---|---|
streamwright://schema/source | JSON Schema (draft 7) of the source engine's source document |
streamwright://schema/stream | JSON Schema (draft 7) of the source engine's stream document |
streamwright://guide/source | The section titles of the source engine's guide |
streamwright://guide/source/{section} | One section of the source engine's guide, found by title |
streamwright://schema/NAME, streamwright://guide/ENGINE[/{section}] | The same for every installed job engine (for example DuckDBJob, SparkJob) |
Server options
| Option | What it does | Default |
|---|---|---|
--transport | stdio, sse or streamable-http | stdio |
--allow-http | Required for sse and streamable-http, which serve over the network | off |
--host HOST | The interface to bind (network transports only) | 127.0.0.1 |
--port PORT | The port to listen on (network transports only) | 8000 |
--root DIR | A folder the tools may read files from (repeatable) | $STREAMWRIGHT_MCP_ROOTS, else the working directory |
Running over the network
To connect from a remote agent or a container, run the server with a network transport. Callers must send the
bearer token you set in STREAMWRIGHT_MCP_TOKEN; the server will not start without it.
STREAMWRIGHT_MCP_TOKEN=YOUR_TOKEN streamwright-mcp --transport sse --allow-http --port 8000 --root ./pipelines
The endpoint is http://localhost:8000/sse (with --transport streamable-http: http://localhost:8000/mcp). For
example, with the Copilot CLI:
copilot mcp add --transport sse --header "Authorization: Bearer YOUR_TOKEN" streamwright http://localhost:8000/sse
The token is a shared secret sent over plain HTTP. Keep the server on 127.0.0.1, or put it behind a proxy that
terminates TLS.
Example prompts
Once connected, ask in plain language. Some examples and what the assistant does:
"List the installed connectors and show me the authentication contract for Google Ads."
It calls list_connectors, then get_connector_contract("google_ads"), and answers from the contract.
"Which key makes a call step retry on HTTP 429?"
It calls search_docs("retry 429"), then opens the best section with the tool call that result names.
"Create a source for PostgreSQL that reads the
usersandorderstables, shape them with DuckDB SQL, and validate it."
It reads the contract, writes the YAML files and checks them with validate_source_config before you run them.
"Make my campaigns job run once per client in parallel, and never let two runs pull the same ad account at the same time; skip accounts that are busy."
It reads get_engine_guide("DuckDBJob", "State, scopes and locks") and adds:
runtime.state.scope: "client:{{ config.client }}";- a
lockwitheach: "{{ config.customer_ids }}", atokenandpolicy: prune.
It checks the job with validate_duckdb_job (passing config values, as --set would), then gives you the
commands from get_cli_reference:
sw duckdb state migrate job.yaml --set client=acme # create the state tables once
sw run job.yaml --set client=acme --set customer_ids=111,222
A run only checks the state tables; --apply-state-migrations lets it create them in development.
"A batch of client acme failed yesterday. Show me why and retry it."
It uses get_cli_reference("duckdb state") to give you:
sw duckdb state list job.yaml --set client=acme # find the batch
sw duckdb state show job.yaml JOB_ID --set client=acme # its pinned inputs and error
sw duckdb state retry job.yaml JOB_ID --set client=acme # resume it with the values it pinned
A retry works while the batch is still failed. With the default runtime.state.failed_job_policy: abandon, the
next run gives the batch up. If every batch must land, set failed_job_policy: retry (the next runs retry it, up to
max_job_attempts) or block (it waits for a manual retry or state abandon).
"Get this job ready for production: its state lives in Postgres and deployments must apply schema changes."
It reads the Migrations part of get_engine_guide("DuckDBJob", "State, scopes and locks"), points
runtime.state.connection at the Postgres connection, and gives you the deployment steps:
sw duckdb state migrate job.yaml --dry-run # review the SQL
sw duckdb state migrate job.yaml # apply it
sw duckdb state check job.yaml # exits 1 while a migration is pending: use it as a gate
Runs never change the schema themselves unless given --apply-state-migrations or
runtime.state.apply_migrations: true.