Skip to main content

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.

In short

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

.vscode/mcp.json
{
"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"]
}
}
}
ClientConfiguration file
Claude DesktopmacOS: ~/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-mcp is not on your PATH, use its full path, for example /path/to/venv/bin/streamwright-mcp (which streamwright-mcp prints it; where streamwright-mcp on 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​

ToolWhat it does
list_connectorsThe 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_docsKeyword 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​

ToolWhat it does
get_connector_contractA 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_guideA 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_typeA 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_guideAn engine's guide, for example DuckDBJob. Without section, the section titles.
Takes: kind, section?
get_core_schemaThe 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_referenceLive help for a streamwright (sw) command, read from the CLI, for example run or duckdb state. Without command, the command list.
Takes: command?

Check​

ToolWhat it does
validate_source_configChecks 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_transformShows 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_jobOne 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 as s3:// are refused.
  • Inline content is limited to 5 MiB.
  • A result over 20,000 characters is shortened and marked "truncated": true with a hint. Narrow the request with operation, section or search_docs.

Resources​

For clients that can attach MCP resources:

URIContent
streamwright://schema/sourceJSON Schema (draft 7) of the source engine's source document
streamwright://schema/streamJSON Schema (draft 7) of the source engine's stream document
streamwright://guide/sourceThe 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​

OptionWhat it doesDefault
--transportstdio, sse or streamable-httpstdio
--allow-httpRequired for sse and streamable-http, which serve over the networkoff
--host HOSTThe interface to bind (network transports only)127.0.0.1
--port PORTThe port to listen on (network transports only)8000
--root DIRA 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
warning

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 users and orders tables, 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 lock with each: "{{ config.customer_ids }}", a token and policy: 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.

See also​