MCP server

dexaflow-mcp is Dexaflow’s Model Context Protocol server (ADR 0050). Point an LLM agent — Claude Desktop, Claude Code, or any MCP client — at your control plane and it can read and reason about your DAGs, runs, task instances, and logs: “which task failed in last night’s sales run, and why?”

Why it matters

Operating an orchestrator is a diagnosis loop: something failed, and you chase it across runs, task instances, and logs. The MCP server hands that loop to an agent. Instead of clicking through the grid or chaining four API calls, you ask a question in plain language and the agent walks the same read surface you would — safely, because it can only see what your token already authorizes.

It is a separate, read-only process. It reaches the control plane only through the Airflow-compatible /api/v2 (via the typed pkg/client), carrying the caller’s token, and is never compiled into leoflow-server. It holds no database, Redis, or Kubernetes access of its own. Built on the official modelcontextprotocol/go-sdk.

Running it

dexaflow-mcp ships alongside the other binaries (installed by the one-command install, or go build ./cmd/dexaflow-mcp). It has two transports.

• stdio (default) — local Lite dev
• Streamable HTTP — the Pro service

export DEXAFLOW_SERVER_URL=http://localhost:8088     # your Lite control plane
export DEXAFLOW_TOKEN="$(dexaflow auth create-token \
  --server http://localhost:8088 \
  --username admin@dexaflow.local --password <your-admin-password>)"
dexaflow-mcp                                          # speaks MCP over stdin/stdout

dexaflow-mcp --transport http --listen :9099 --server https://leoflow.internal

docker run --rm -p 9099:9099 ghcr.io/dexadata/dexaflow-mcp:v<version>@sha256:<digest> \
  --transport http --listen :9099 --server https://leoflow.internal

Flags and environment

OAuth sign-in discovery

MCP clients that sign in with OAuth, as the MCP authorization specification describes (claude.ai connectors and ChatGPT among them), find the authorization server from the MCP server itself. With --resource and --authorization-servers set, the http transport:

• serves the protected resource metadata (RFC 9728) at the path derived from the resource (/.well-known/oauth-protected-resource/mcp for a resource ending in /mcp) and at /.well-known/oauth-protected-resource:

  {
    "resource": "https://dexaflow.example.com/mcp",
    "authorization_servers": ["https://auth.example.com"],
    "scopes_supported": ["dexaflow:read"],
    "bearer_methods_supported": ["header"]
  }
  

• answers a request to /mcp without a bearer with 401 and WWW-Authenticate: Bearer resource_metadata="<metadata URL>", which starts the client’s sign-in.

dexaflow-mcp --transport http --server https://dexaflow.internal \
  --resource https://dexaflow.example.com/mcp \
  --authorization-servers https://auth.example.com \
  --scopes dexaflow:read

Dexaflow is not the authorization server. It points clients at yours, and the tokens they bring are verified by /api/v2 on every call like any other bearer, so they must be ones the control plane accepts, such as tokens of your trusted issuer for one of its bearer audiences. Without these flags nothing changes.

Auth: getting a token

The MCP passes the caller’s Dexaflow JWT through to /api/v2 and never mints one (ADR 0050 D9). Obtain one from the control plane with your admin login:

dexaflow auth create-token \
  --server http://localhost:8088 \
  --username admin@dexaflow.local \
  --password <your-admin-password>

Use that token as DEXAFLOW_TOKEN (stdio) or as the request Authorization: Bearer header (http). Tokens are short-lived; treat them as secrets (never log them, never commit them).

Tools

Tools are the surface most MCP clients render first (ADR 0050 D7), so the server leads with a few high-value ones. All are read-only.

Run control

With --run-control, the server also registers tools that change state (ADR 0067). Without the flag they do not exist at all. Each call uses the caller’s token, so the control plane’s roles decide, and for a trusted-issuer bearer token, its dexaflow:run scope too.

A call that needs a plan changes nothing. It returns what would happen and a plan_id, and the model is told to show it to the user and to call apply_plan only if they agree.

• A plan carries the exact operation, signed with the plan key. The model cannot change it, only hand it back.
• A plan lasts 10 minutes and is bound to the caller. Over HTTP that is the bearer’s issuer (iss), subject (sub), tenant (tenant_id, tenant or tid), client (azp, else client_id) and scope set, so another user, tenant, client or narrower token cannot apply it. A token without iss, sub or a tenant cannot plan. A refreshed token, or one whose roles or email changed, still applies the plan; the control plane checks the caller’s permissions on the apply call itself.
• Apply checks again before acting. If the task instances are no longer in the states the plan showed, or the DAG’s paused flag or schedule changed, or more runs are queued than the plan showed, apply_plan refuses and asks for a new plan. A plan therefore applies once.
• A clear over more than 200 task instances is refused. Narrow it with task_ids or use the UI.
• A clear runs only what its preview showed. The clear that follows a preview names the previewed tasks and expands no further, so a task that fails in between is not cleared unseen.

Generate the plan key once and give every replica the same file:

openssl rand -base64 48 > plan.key
chmod 600 plan.key
dexaflow-mcp --transport http --run-control --plan-key-file plan.key

Changing the key invalidates the plans made in the last 10 minutes, nothing else.

Resources

Addressable, read-only resources — the agent picks the URI; the control plane authorizes each read via the pass-through token, so a resource can only surface what the caller may already see. Log and source reads are sanitized and truncated by construction (untrusted content, ADR 0050 D10).

Prompts

Prompts are ready-made requests a client offers its user, often as a slash command. Both are read-only: they read the control plane with the caller’s token to find the runs to look at, then ask the model to make the tool calls they name.

The control plane has no cross-DAG run query, so without a dag_id the prompts read the first page of DAGs (up to 200) and a page of runs for each. When there are more DAGs, the prompt says how many it did not check.

A prompt reaches the model as the user’s own message, so it repeats a DAG or run id only when the id is plain: 1 to 128 ASCII letters, digits or _.:+@~=-, which covers generated run ids such as manual__2026-10-08T12:00:00+00:00. Any other id (a run id with spaces or quotes, say, which whoever triggered the run chose) is withheld, even from links. The prompt then links the DAG and asks the model to get the ids from the user.

Links into the UI

With --ui-base-url set, results carry a web_url that opens the entity in the Dexaflow UI. Without it the field is absent.

On initialize, the server’s instructions tell the model to link the DAGs, runs, tasks and log lines it mentions with web_url, and never to build UI links itself. Text resources (log://, dag://source/) carry no link.

Wiring an MCP client (Claude Desktop)

Add dexaflow-mcp to your client’s MCP server config. For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "dexaflow": {
      "command": "dexaflow-mcp",
      "env": {
        "DEXAFLOW_SERVER_URL": "http://localhost:8088",
        "DEXAFLOW_TOKEN": "<paste a JWT from `dexaflow auth create-token`>"
      }
    }
  }
}

If dexaflow-mcp is not on the launcher’s PATH, use its absolute path as command (e.g. ~/.dexaflow/bin/dexaflow-mcp). Restart the client, and Dexaflow’s tools and resources appear. Start with “list my DAGs” or “diagnose the latest failed run of <dag_id>”.

Security: the blast radius

See also

• ADR 0050 — Model Context Protocol server: the full design, the security posture, and the untrusted-content threat model.
• Go packages → pkg/client: the typed /api/v2 client the MCP is built on.
• HTTP API (Scalar): the /api/v2 surface itself.