dagster-mono-mcp

A single-tool MCP server for Dagster. One tool, five actions, minimal token overhead.

Dagster has an official MCP server, but I couldn't get it working easily. This is a minimal alternative that covers the actions you actually need when debugging pipelines with an LLM: listing runs, inspecting run details, reading logs, and raw GraphQL for everything else.

Supports Cloudflare Access for Dagster instances behind Zero Trust — an easy, free way to secure your Dagster instance.

Install

Claude Code

Project-scoped (.mcp.json in your project root):

{
  "mcpServers": {
    "dagster": {
      "command": "npx",
      "args": ["-y", "github:pjatx/dagster-mono-mcp"],
      "env": {
        "DAGSTER_GRAPHQL_URL": "https://dagster.example.com/graphql",
        "CF_ACCESS_CLIENT_ID": "your-client-id",
        "CF_ACCESS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Global (~/.claude.json — available in all projects):

{
  "mcpServers": {
    "dagster": {
      "command": "npx",
      "args": ["-y", "github:pjatx/dagster-mono-mcp"],
      "env": {
        "DAGSTER_GRAPHQL_URL": "https://dagster.example.com/graphql"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "dagster": {
      "command": "npx",
      "args": ["-y", "github:pjatx/dagster-mono-mcp"],
      "env": {
        "DAGSTER_GRAPHQL_URL": "https://dagster.example.com/graphql",
        "CF_ACCESS_CLIENT_ID": "your-client-id",
        "CF_ACCESS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "dagster": {
      "command": "npx",
      "args": ["-y", "github:pjatx/dagster-mono-mcp"],
      "env": {
        "DAGSTER_GRAPHQL_URL": "https://dagster.example.com/graphql",
        "CF_ACCESS_CLIENT_ID": "your-client-id",
        "CF_ACCESS_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Environment Variables

Variable	Default	Required
DAGSTER_GRAPHQL_URL	http://localhost:3000/graphql	No
CF_ACCESS_CLIENT_ID	—	No (required if behind CF Access)
CF_ACCESS_CLIENT_SECRET	—	No (required if behind CF Access)

Usage

Single tool dagster with action dispatch:

List runs

{"action": "runs"}
{"action": "runs", "status": "FAILURE"}
{"action": "runs", "job": "my_job", "limit": 5}

Run details

{"action": "run", "id": "<run-id>"}

Event logs

{"action": "logs", "id": "<run-id>"}
{"action": "logs", "id": "<run-id>", "limit": 100}

Raw GraphQL

{"action": "graphql", "query": "{ version }"}
{"action": "graphql", "query": "query($id: ID!) { runOrError(runId: $id) { __typename } }", "variables": {"id": "abc123"}}

Help

{"action": "help"}

Returns full documentation including available statuses, all parameters, and example queries.

Design

This project follows the mono-tool pattern: one MCP tool with action dispatch instead of many small tools. Fewer tools means less token overhead for the LLM and simpler tool selection — the model doesn't have to choose between a dozen similar-sounding tools. Inspired by Cloudflare's Code Mode post on rethinking how LLMs interact with MCP servers.

Development

npm install
npm run build    # esbuild bundle -> dist/index.js
npm start        # run the MCP server (stdio transport)

License

MIT