MCP server
Point an MCP client such as Claude Code at
https://api.dagweave.com/api/v1/mcp with an API token. An
agent can then look up runs, read a failed step’s logs and check a draft
workflow. With more scopes it can save workflows, start runs, push to Git and
manage your team, the same as you would in the app.
There are 120 tools: 57 read and 63 write. Each one calls a public API endpoint with your token, so the agent can do exactly what the token can. Every API endpoint has a tool, and the few things neither can do are under What stays in the app.
Create a token
Section titled “Create a token”Create an API token with the scopes for the tools you want the agent to have.
| Scope | Tools |
|---|---|
runs:read |
dagweave_list_runs, dagweave_get_run, dagweave_list_workflow_runs, dagweave_list_adopted_runs, dagweave_get_run_diff, dagweave_get_metrics, dagweave_get_workflows_health, dagweave_get_workflow_metrics, dagweave_list_schedule_deployments |
runs:logs |
dagweave_get_node_logs |
runs:artifacts |
dagweave_list_run_artifacts, dagweave_read_run_artifact |
workflows:read |
dagweave_list_workflows, dagweave_get_workflow, dagweave_list_node_types, dagweave_validate_workflow, dagweave_decompile_workflow, dagweave_get_ir_schema, dagweave_list_blueprints, dagweave_list_catalog, dagweave_check_expression, dagweave_evaluate_expression, dagweave_get_expression_vocabulary, dagweave_preview_schedule |
git:read |
dagweave_get_git_status, dagweave_list_git_repos, dagweave_get_workflow_git_link |
templates:read |
dagweave_list_templates, dagweave_get_template, dagweave_list_marketplace, dagweave_get_marketplace_listing |
audit:read |
dagweave_list_audit_events, dagweave_list_audit_actions |
triggers:read |
dagweave_list_triggers, dagweave_list_workflow_triggers |
clusters:read |
dagweave_list_connectors, dagweave_list_machines, dagweave_get_connector_logs, dagweave_get_connector_health, dagweave_list_sources, dagweave_list_source_items, dagweave_get_source_item, dagweave_list_cluster_definitions |
team:read |
dagweave_list_teams, dagweave_list_members, dagweave_get_notifications, dagweave_list_invites, dagweave_list_groups, dagweave_list_group_members, dagweave_get_sso, dagweave_list_grants, dagweave_list_dispatch_scopes, dagweave_get_dispatch_scoping, dagweave_list_run_identities, dagweave_list_run_identity_templates, dagweave_get_run_identity_approval, dagweave_get_entitlements, dagweave_list_plans, dagweave_get_log_usage |
runs:write |
dagweave_run_workflow, dagweave_rerun_run, dagweave_stop_run, dagweave_terminate_run, dagweave_suspend_run, dagweave_resume_run, dagweave_retry_run, dagweave_cancel_run, dagweave_list_run_targets, dagweave_run_trigger, dagweave_upload_run_input, dagweave_deploy_schedule, dagweave_remove_schedule, dagweave_share_run, dagweave_unshare_run |
triggers:write |
dagweave_create_trigger, dagweave_update_trigger, dagweave_delete_trigger |
workflows:write |
dagweave_create_workflow, dagweave_update_workflow, dagweave_set_workflow_labels, dagweave_duplicate_workflow, dagweave_unpin_workflow_versions, dagweave_set_step_resources, dagweave_import_manifests, dagweave_import_from_github, dagweave_import_from_cluster |
workflows:delete |
dagweave_delete_workflow |
git:write |
dagweave_link_git, dagweave_link_workflow_to_git, dagweave_unlink_workflow_from_git, dagweave_sync_workflow_from_git, dagweave_push_to_git |
templates:write |
dagweave_publish_template, dagweave_set_template_published, dagweave_install_from_marketplace, dagweave_decompose_workflow |
clusters:write |
dagweave_delete_connector, dagweave_delete_machine, dagweave_create_source, dagweave_delete_source |
team:write |
dagweave_rename_team, dagweave_add_member, dagweave_set_member_role, dagweave_remove_member, dagweave_set_notifications, dagweave_set_log_retention, dagweave_invite_member, dagweave_revoke_invite, dagweave_create_group, dagweave_rename_group, dagweave_delete_group, dagweave_add_group_member, dagweave_remove_group_member, dagweave_remove_group_invite, dagweave_set_sso, dagweave_set_sso_enforced, dagweave_delete_sso, dagweave_ask_for_more, dagweave_share, dagweave_unshare, dagweave_grant_dispatch_scope, dagweave_revoke_dispatch_scope, dagweave_delete_dispatch_scope, dagweave_set_dispatch_scoping, dagweave_create_ephemeral_namespace, dagweave_delete_ephemeral_namespace, dagweave_create_run_identity, dagweave_delete_run_identity, dagweave_decide_run_identity, dagweave_set_run_identity_approval |
No scope includes another. tools/list only shows tools the token can call, so
an agent without runs:logs won’t see the logs tool. The instructions the
server sends on initialize make up for that: they list each scope the token
lacks and the tools it would add, so the agent can tell you which scope to add.
Give a debugging agent both runs:read and runs:logs.
You can change a token’s scopes without making a new one. The client reads the tool list when it connects, so reconnect it afterwards.
Put write scopes on their own token. Then you can revoke it without breaking your read-only setups.
Connect a client
Section titled “Connect a client”Any client that speaks MCP over HTTP and can send a bearer header works. For an
mcpServers JSON config, such as Claude Code’s .mcp.json:
{ "mcpServers": { "dagweave": { "type": "http", "url": "https://api.dagweave.com/api/v1/mcp", "headers": { "Authorization": "Bearer dwk_your_token_here" } } }}With the Claude Code CLI:
claude mcp add --transport http dagweave https://api.dagweave.com/api/v1/mcp \ --header "Authorization: Bearer $DAGWEAVE_TOKEN"The server takes one JSON-RPC request per POST and answers in the same
response. No SSE, batching, GET or session ids.
It supports initialize, ping, tools/list and tools/call. It prefers
protocol version 2025-06-18 and also accepts 2025-03-26 and 2024-11-05.
Ask for any other version and the server answers with 2025-06-18. Notifications get an empty 202.
Every request needs a valid token, initialize included. Only tools/call
counts against your rate limit, one request per call.
How the tools behave
Section titled “How the tools behave”Each tool returns its endpoint’s JSON body unchanged, as one text block. The public API reference covers every field.
A call with an undeclared argument, or one of the wrong type, is refused before anything runs.
readOnlyHint is true on the 57 read tools and false on the 63 write tools.
This page covers the tools an agent reaches for most. The rest take the same
fields as their API endpoint, plus idempotencyKey on a write, and
each tool’s description says what it needs.
Idempotency keys
Section titled “Idempotency keys”Every write tool needs an idempotencyKey argument, sent as the endpoint’s
Idempotency-Key header. Use a new value, such as a UUID, for each action.
Reuse a key only to retry a call whose answer you never got. You get the first
answer back and the work isn’t done twice. The same key on a different request
fails with this Idempotency-Key was already used for a different request.
Read tools
Section titled “Read tools”dagweave_list_runs
Section titled “dagweave_list_runs”Requires runs:read. Your team’s runs, newest first.
| Argument | Type | Description |
|---|---|---|
limit |
integer | How many runs to return. Defaults to 50, maximum 200. |
offset |
integer | How many runs to skip. |
includeTest |
boolean | Include test runs started from the builder. They’re left out by default. |
phase |
string | Only runs in this phase. failed takes every kind of failure, running takes pending runs too, and queued takes runs waiting in Dagweave’s queue. |
connectorId |
string | Only runs that went to this connector or machine. |
since |
string | Only runs created at or after this RFC 3339 time. |
Each row has id, workflowId, workflowName, connectorId, phase,
message, startedAt, finishedAt and createdAt, plus triggerId,
source, actorId and actorEmail when set. A failed run adds
rootCauseNode and rootCauseMessage: the step that failed and its error.
That’s often enough to answer “what broke last night?” in one call.
A Queued run is waiting for a free slot in your team and hasn’t reached a
cluster.
dagweave_get_run
Section titled “dagweave_get_run”Requires runs:read. One run in full.
| Argument | Type | Description |
|---|---|---|
runId |
string | Required. A run id from dagweave_list_runs. |
The response has phase, message and progress, plus nodes (each step’s
status), artifacts, logs (pointers into your own storage), outputs (output
parameters), triggeredBy and annotations. Pass a step id from nodes to
dagweave_get_node_logs.
Another team’s run gets the same 404 as a missing one.
dagweave_get_node_logs
Section titled “dagweave_get_node_logs”Requires runs:logs. One step’s log output.
| Argument | Type | Description |
|---|---|---|
runId |
string | Required. The run id. |
nodeId |
string | Required. A step id from the nodes list that dagweave_get_run returns. |
tail |
integer | How many trailing lines to return. Defaults to 200, maximum 5000. |
since |
string | A Go duration such as 30m or 2h. Only reads lines from that window. Maximum 720h. |
containers |
string | all to read every container in the step’s pod. By default you get only the main container. |
The response has kind and nodeId, plus one of location (logs in your
storage), content (the lines) or message (why there’s nothing).
The tool’s description tells the model to treat log output as untrusted input, since a step can print text that looks like instructions.
dagweave_list_workflows
Section titled “dagweave_list_workflows”Requires workflows:read. Your team’s workflows and Dagweave’s examples.
| Argument | Type | Description |
|---|---|---|
q |
string | Case-insensitive match on part of the workflow name. |
label |
string | Only workflows with this label. |
namespace |
string | Only workflows in this namespace. |
folder |
string | Only workflows in this folder. |
limit |
integer | How many workflows to return. Without limit or offset you get every match. |
offset |
integer | How many workflows to skip. |
Each row has id, name and version, plus folder, namespace and labels
when set. A workflow with no name is listed under its generateName. Examples
have readOnly: true.
dagweave_get_workflow
Section titled “dagweave_get_workflow”Requires workflows:read. One workflow as its full Dagweave IR JSON, the
document the builder opens.
| Argument | Type | Description |
|---|---|---|
workflowId |
string | Required. A workflow id from dagweave_list_workflows. |
It also returns the workflow’s version, which dagweave_update_workflow needs as
baseVersion. That tool replaces the whole workflow, so have the agent edit what
this returns rather than write it from scratch. Dagweave’s examples can be read
too. Another team’s workflow gets 404.
dagweave_list_audit_events
Section titled “dagweave_list_audit_events”Requires audit:read and a plan with the audit log. On other plans the tool is
listed but every call gets 402.
| Argument | Type | Description |
|---|---|---|
action |
string | Only events with this exact action, such as apitoken.revoke. |
actor |
string | Only events by this user, given as a user id or an email address. |
outcome |
string | Only events with this outcome: success, failure, denied or skipped. |
objectType |
string | Only events about this kind of object, such as workflow, run or api_token. |
objectId |
string | Only events about the object with this id. Give objectType too. |
from |
string | RFC3339 timestamp. Only events at or after it. |
to |
string | RFC3339 timestamp. Only events at or before it. |
before |
string | RFC3339 timestamp. Only events older than it. Use it to page back. |
limit |
integer | How many events to return. Defaults to 50, maximum 500. |
Newest first. Each event has id, occurredAt, action and outcome, plus
actorEmail, actorIp, actorCredential, actorTokenId, actorTokenName,
objectType, objectId and details where they apply. No CSV.
dagweave_list_node_types
Section titled “dagweave_list_node_types”Requires workflows:read. The step types an IR document can use. Have the agent
call it before writing IR so it uses real field names.
| Argument | Type | Description |
|---|---|---|
typeId |
string | Return only this step type, with its config schema. Omit it for the full list. |
A JSON array sorted by typeId. Each entry has typeId, label,
description, version, core, podBased, paletteHidden and ports.
ports has inputs and outputs, and each port has a name and a type of
parameter or artifact.
A step’s typeId must match an entry’s typeId. To pin a version, set the
step’s nodeVersion to the entry’s version. Ask for one typeId to get
configSchema, the JSON Schema for its config block.
An unknown typeId gets 404 with every valid id:
no node type "run-scrpt". dagweave has: ...| Field | When it’s false or true |
|---|---|
podBased |
false means the step doesn’t get its own pod. It runs on the workflow’s agent or not at all, so pod settings such as resources, env and placement have no effect. |
core |
false marks a type that reaches past the workflow itself: Resource, ContainerSet and Plugin. Every plan can use every type. |
paletteHidden |
true means the type exists so that imported Argo templates stay editable. You can use it, but a new workflow should use the type it mirrors. Import-only types lists the pairs. |
Catalog items aren’t in the list. A step that uses one has
typeId: "catalog-ref", resolved on save. To browse the
catalog, use dagweave_list_catalog. The list is the same for every
team.
dagweave_validate_workflow
Section titled “dagweave_validate_workflow”Requires workflows:read. Checks a draft without saving or running it and
returns the Argo manifest it compiles to. Call it as often as you like.
| Argument | Type | Description |
|---|---|---|
workflow |
string | Required. The whole document, as Argo YAML (Workflow, WorkflowTemplate, ClusterWorkflowTemplate or CronWorkflow) or Dagweave IR JSON. |
A document with top-level nodes and edges is read as IR, anything else as
Argo YAML.
The response has valid, format (argo-yaml or dagweave-ir), faults and
manifest. Each fault has severity, rule, message and, when it can be
pinned down, a path into your document. An error means it won’t run. A
warning means it’ll run but part of it does nothing.
It catches unknown Argo fields, undefined templates and tasks, dependencies on missing tasks, unused parameters and anything the compiler rejects. It also checks the manifest against the cluster’s admission rules, so a draft that passes won’t be rejected on submit.
Steps your plan won’t let you save come back as faults with rule plan, naming
the step and the cheapest plan that allows it. The save runs the same check, so
a draft with no plan faults won’t be refused for its steps.
dagweave_list_workflow_runs
Section titled “dagweave_list_workflow_runs”Requires runs:read. One workflow’s runs, newest first.
| Argument | Type | Description |
|---|---|---|
workflowId |
string | Required. |
phase |
string | Only runs in this phase. failed matches every kind of failure. |
since |
string | RFC3339 timestamp. Only runs created at or after it. |
includeTest |
boolean | Include test runs. |
limit, offset |
integer | Page size, default 50 and maximum 200, and runs to skip. |
dagweave_list_run_targets
Section titled “dagweave_list_run_targets”Requires runs:write. Lists the clusters and namespaces a workflow can run in,
in the same order as the Run dialog, and says why any of them can’t take it.
Under machines it lists your own machines running
Dagweave Local, with their status and the namespace (argo)
and argoInstanceId (local) a run on one names.
| Argument | Type | Description |
|---|---|---|
workflowId |
string | Required. |
dagweave_list_connectors
Section titled “dagweave_list_connectors”Requires clusters:read. Your connectors with their status, version, last
heartbeat and the namespaces each one serves. No arguments.
dagweave_list_triggers
Section titled “dagweave_list_triggers”Requires triggers:read. Your triggers: what each runs, where, its type, whether
it’s enabled, when it last fired and the run it last started. A webhook trigger
has its webhookUrl and an sns or s3 trigger its snsUrl. No arguments.
Write tools
Section titled “Write tools”dagweave_create_workflow
Section titled “dagweave_create_workflow”Requires workflows:write. Saves a new workflow and returns its id and version.
| Argument | Type | Description |
|---|---|---|
workflow |
string | Required. The whole document, in either format dagweave_validate_workflow accepts. |
idempotencyKey |
string | Required. See Idempotency keys. |
It runs the same checks as dagweave_validate_workflow. On an error the call
fails with the faults and nothing is saved, so validate first.
At your plan’s workflow limit you get 429. A catalog item your plan doesn’t
include gets 402.
The reply is {"id": "...", "version": "..."}. Keep the version:
dagweave_update_workflow needs it. dagweave_get_workflow and
dagweave_list_workflows return it too.
Saving doesn’t start a run. This tool always creates. To change a workflow, use
dagweave_update_workflow.
dagweave_update_workflow
Section titled “dagweave_update_workflow”Requires workflows:write. Replaces a stored workflow with a new document and
returns the new version.
| Argument | Type | Description |
|---|---|---|
workflowId |
string | Required. A workflow id from dagweave_list_workflows. |
workflow |
string | Required. The whole replacement document. |
baseVersion |
string | Required. The version the last create or update of this workflow returned. |
idempotencyKey |
string | Required. See Idempotency keys. |
Anything left out is removed. Have the agent edit what dagweave_get_workflow
returns.
If someone saved after baseVersion, the call fails with a message naming the
current version, and nothing changes. Get the workflow again, reapply the edit and
send that version. Dagweave doesn’t merge, so an agent’s slow rewrite can’t
clobber your edit.
If someone has the workflow open in Dagweave while your agent updates it, nothing gets overwritten. They’ll be asked whether to reload or keep their changes.
A draft with an error fails with its faults and changes nothing. Examples get
404.
The reply is {"id": "...", "version": "..."}.
dagweave_set_workflow_labels
Section titled “dagweave_set_workflow_labels”Requires workflows:write. Replaces a workflow’s labels.
| Argument | Type | Description |
|---|---|---|
workflowId |
string | Required. A workflow id from dagweave_list_workflows. |
labels |
array of strings | Required. Every label the workflow should end up with. An empty list clears them. |
idempotencyKey |
string | Required. See Idempotency keys. |
Include the labels you want to keep. They come from dagweave_list_workflows,
which needs workflows:read. Without it, the agent overwrites labels it can’t
see.
labels must be a JSON array. "prod,etl" fails with
argument "labels" must be a array.
The definition doesn’t change and nothing runs. Success is an empty text block.
Examples get 404.
dagweave_delete_workflow
Section titled “dagweave_delete_workflow”Requires workflows:delete, which workflows:write doesn’t include.
| Argument | Type | Description |
|---|---|---|
workflowId |
string | Required. A workflow id from dagweave_list_workflows. |
idempotencyKey |
string | Required. See Idempotency keys. |
You can’t undo it. Past runs keep the deleted workflow’s id. Dagweave also removes WorkflowTemplates it installed for this workflow that nothing else uses. See What does not come back.
Success is an empty text block. Examples get 404.
dagweave_run_workflow
Section titled “dagweave_run_workflow”Requires runs:write. Starts a run of a stored workflow on one of your clusters
and returns the run id.
| Argument | Type | Description |
|---|---|---|
workflowId |
string | Required. A workflow id from dagweave_list_workflows. |
connectorId |
string | Required. The connector or machine to run on. |
namespace |
string | Required. The Kubernetes namespace on that connector’s cluster. argo for a machine. |
argoInstanceId |
string | The Argo instance to use, when the connector serves more than one. local for a machine. |
params |
object | Values for the workflow’s parameters, name to string value. A parameter you leave out keeps its saved value. A required one with no default must be given. |
annotations |
object | Your own annotations for the run’s Workflow, key to string value. The same limits as the HTTP endpoint apply. |
inputArtifacts |
object | Small files for the workflow’s input artifacts, artifact name to base64 content. |
inputHandles |
object | Bigger files, artifact name to the handle dagweave_upload_run_input returned. See Files for a run. |
idempotencyKey |
string | Required. See Idempotency keys. |
Use dagweave_list_run_targets to pick connectorId and namespace. Only a
machine’s owner can send it a run, and the machine has to be running
dagweave listen to pick it up.
This starts real work. The tool’s description tells the model to ask you first.
To keep an agent from starting runs, leave runs:write off its token.
The reply is {"runId": "..."}. Follow it with dagweave_get_run.
dagweave_rerun_run
Section titled “dagweave_rerun_run”Requires runs:write. Runs a past run again and returns the new run id.
| Argument | Type | Description |
|---|---|---|
runId |
string | Required. A run id from dagweave_list_runs. |
idempotencyKey |
string | Required. See Idempotency keys. |
It reuses the original’s workflow, connector, namespace and runtime parameters, and the agent can’t change them. The tool’s description tells the model to ask you first.
The reply is {"runId": "..."}.
Builder test runs can’t be rerun here. The call fails and says to use the builder.
dagweave_stop_run
Section titled “dagweave_stop_run”Requires runs:write. Stops a running run, like Stop run in the run view.
| Argument | Type | Description |
|---|---|---|
runId |
string | Required. A run id from dagweave_list_runs. |
idempotencyKey |
string | Required. See Idempotency keys. |
Running steps stop, exit handlers still run and the run ends as failed. The
tool’s description tells the model to ask you first. A run that isn’t running,
or is still queued, is refused. Check the result with dagweave_get_run.
dagweave_terminate_run
Section titled “dagweave_terminate_run”Requires runs:write. Terminates a running run, like Terminate run in the run
view. The run ends at once and its exit handlers don’t run. The tool’s
description tells the model to ask you first.
| Argument | Type | Description |
|---|---|---|
runId |
string | Required. A run id from dagweave_list_runs. |
idempotencyKey |
string | Required. See Idempotency keys. |
A run that isn’t running, or is still queued, is refused.
dagweave_suspend_run
Section titled “dagweave_suspend_run”Requires runs:write. Suspends a running run, like Suspend run in the run
view. Steps already running finish and no new ones start. Same arguments and
refusals as dagweave_terminate_run, and a run that is already stopping or
terminating is refused too.
dagweave_resume_run
Section titled “dagweave_resume_run”Requires runs:write. Resumes a suspended run, like Resume run in the run
view. Same arguments as dagweave_terminate_run. A connector older than 0.16.0
is refused.
dagweave_retry_run
Section titled “dagweave_retry_run”Requires runs:write. Retries a failed run on the same run, like Retry run in
the run view. Steps that succeeded are kept. It is not dagweave_rerun_run, which
starts a new run. Same arguments as dagweave_terminate_run. A run that hasn’t
failed, or a connector older than 0.16.0, is refused.
dagweave_cancel_run
Section titled “dagweave_cancel_run”Requires runs:write. Cancels a queued run, like Cancel run in the run view.
| Argument | Type | Description |
|---|---|---|
runId |
string | Required. |
idempotencyKey |
string | Required. See Idempotency keys. |
A run that has reached its cluster is refused. Use dagweave_stop_run.
dagweave_create_trigger
Section titled “dagweave_create_trigger”Requires triggers:write. Creates a trigger. It takes the same fields as
POST /api/v1/triggers, plus idempotencyKey.
workflowId, connectorId, namespace, type and idempotencyKey are required.
A new trigger stays switched off unless you set enabled: true. Create webhook
triggers in the app.
dagweave_update_trigger
Section titled “dagweave_update_trigger”Requires triggers:write. Read the current values with dagweave_list_triggers
first.
| Argument | Type | Description |
|---|---|---|
triggerId |
string | Required. |
namespace |
string | Required. |
enabled |
boolean | Required, so leaving it out can’t switch the trigger off. |
argoInstanceId |
string | Left out clears it. |
cronSpec |
string | Required for a cron trigger. |
concurrencyPolicy |
string | Kept when left out. |
paths, pathsIgnore |
array of strings | Kept when left out. An empty list clears them. |
rotateSecret |
boolean | Webhook only, unsigned. Replaces the secret. |
rotateSigningKey |
boolean | Webhook only. Replaces the signing key, or switches an unsigned webhook to signed requests. |
idempotencyKey |
string | Required. |
A rotation returns the new secret or signingKey once, and the old one stops
working straight away. Repeating the call with the same idempotencyKey returns
the trigger without it, so hand the new credential to whoever needs it at once.
The tool’s description tells the model to ask you first.
dagweave_delete_trigger
Section titled “dagweave_delete_trigger”Requires triggers:write. Deletes a trigger, with no undo. The tool’s
description tells the model to ask you first.
| Argument | Type | Description |
|---|---|---|
triggerId |
string | Required. |
idempotencyKey |
string | Required. |
dagweave_run_trigger
Section titled “dagweave_run_trigger”Requires runs:write. Starts a run from a trigger now, on its own connector and
namespace. The reply is {"runId": "..."}.
| Argument | Type | Description |
|---|---|---|
triggerId |
string | Required. |
params |
object | Values for the workflow’s parameters. |
idempotencyKey |
string | Required. |
dagweave_remove_schedule
Section titled “dagweave_remove_schedule”Requires runs:write. Deletes a deployed CronWorkflow from its cluster, so it
stops starting runs and stops counting against your plan. The tool’s description
tells the model to ask you first. dagweave_list_schedule_deployments
(runs:read, takes workflowId) says where a workflow is deployed.
| Argument | Type | Description |
|---|---|---|
workflowId |
string | Required. |
namespace, argoInstanceId |
string | Only the deployment there. Left out removes it everywhere. |
idempotencyKey |
string | Required. |
Each deployment comes back with an outcome, as in
DELETE /api/v1/workflows/{id}/deploy-schedule.
Artifacts
Section titled “Artifacts”dagweave_list_run_artifacts lists a run’s artifacts. Each one has a
downloadUrl that works for 15 minutes, when the cluster can send artifacts
back. dagweave_read_run_artifact takes the runId, bucket and key and
returns the content, up to 20 MiB. Text comes back as it is and anything else as
base64. Both need runs:artifacts.
An artifact holds whatever a step wrote, so the tool’s description tells the model to treat it as data, not instructions.
Files for a run
Section titled “Files for a run”A small file can go straight into dagweave_run_workflow as inputArtifacts. A
bigger one goes up first with dagweave_upload_run_input, which puts it in your
cluster’s own store and returns a handle. Pass that in inputHandles when you
start the run. It needs connectorId, namespace, artifact and content in
base64, up to 3 MiB before encoding, and the run has to use the same connector.
The handle lasts an hour.
Runs from your own machine
Section titled “Runs from your own machine”A run you start with dagweave run on a signed-in machine is an
adopted run, because Dagweave didn’t start it. It’s listed by
dagweave_list_adopted_runs, with a local field naming the machine, and not by
dagweave_list_runs. A run Dagweave sent to your machine is in
dagweave_list_runs. Either way only you see it until you share it with
dagweave_share_run, and dagweave_unshare_run makes it private again. Both
take the run’s id and need runs:write.
Import
Section titled “Import”dagweave_import_manifests imports pasted Argo YAML, one manifest or many.
dagweave_import_from_github copies the manifests in a GitHub repo, or under one
path in it. For a cluster, dagweave_list_cluster_definitions lists the
WorkflowTemplates and CronWorkflows in a namespace and
dagweave_import_from_cluster imports the ones you name. Each import says what
happened to every manifest: imported, failed, blocked or skipped.
Imports need workflows:write, except the cluster listing, which only reads and
needs clusters:read.
These go through your team’s GitHub App.
| Tool | Does |
|---|---|
dagweave_get_git_status |
Whether the GitHub App is set up and which accounts are connected. |
dagweave_list_git_repos |
The repos it can reach. |
dagweave_link_git |
Links a file, or every Argo file in a folder. Each becomes a workflow that follows Git. |
dagweave_get_workflow_git_link |
Where a linked workflow’s file lives and whether it’s ok, missing or unreadable. |
dagweave_link_workflow_to_git |
Links an existing workflow to one file. Its body is replaced with the file’s. |
dagweave_unlink_workflow_from_git |
Unlinks it. It stays as a workflow you can edit. |
dagweave_sync_workflow_from_git |
Re-reads the file at the tip of its branch now. |
dagweave_push_to_git |
Push to Git, as a pull request or a commit. |
A linked workflow can’t be edited in Dagweave. To change one, have the agent send
the edit to dagweave_push_to_git in workflow, with the contentHash it read.
If the file changed in Git since then, the push is refused, unless it opens a
pull request with overwrite. Pushing changes a real repo, so the tool’s
description tells the model to ask you first.
The Team settings screens are all tools: members, invites, groups, alerts, SSO,
sharing, dispatch scopes and run identities. Reads need team:read and changes
need team:write. The app’s own Owner and Admin checks still apply, so a token
can only change what its owner could.
dagweave_invite_member emails the invite and never returns the link. If the
reply says the email didn’t go, revoke the invite and invite them from the app.
dagweave_set_sso sets the domain, but proving you own it happens in the app.
What stays in the app
Section titled “What stays in the app”A few things aren’t tools, because they make a credential, show a secret once or need you to sign in somewhere in your browser:
- making API tokens, team tokens and GitHub trust rules
- adding a connector
- creating a webhook trigger (rotating one’s secret or signing key is
dagweave_update_trigger) - proving an SSO domain
- claiming a GitHub App installation
- billing checkout and the billing portal
- making a team or switching teams, since a token belongs to one team
- signing in, and everything else about your own account
- starting a builder test run
A tool call answers once, so to follow a run the agent polls dagweave_get_run.
Example call
Section titled “Example call”POST /api/v1/mcp HTTP/1.1Host: api.dagweave.comAuthorization: Bearer dwk_...Content-Type: application/json
{"jsonrpc":"2.0","id":3,"method":"tools/call", "params":{"name":"dagweave_list_runs","arguments":{"limit":1}}}{ "jsonrpc": "2.0", "id": 3, "result": { "content": [ { "type": "text", "text": "[{\"id\":\"3f9a1c07b2e4d856\",\"workflowId\":\"a41c09e7d2b35f18\",\"workflowName\":\"nightly etl\",\"connectorId\":\"c7d02e5a9b1f4638\",\"source\":\"cron\",\"phase\":\"Failed\",\"message\":\"pod deleted\",\"rootCauseNode\":\"transform\",\"rootCauseMessage\":\"exit code 137\",\"startedAt\":\"2026-07-25T02:00:04Z\",\"finishedAt\":\"2026-07-25T02:06:41Z\",\"createdAt\":\"2026-07-25T02:00:00Z\"}]" } ], "isError": false }}text is exactly what GET /api/v1/runs?limit=1 returns.
Errors
Section titled “Errors”Token, plan and rate-limit problems set the HTTP status and return JSON-RPC
error -32001. Your client sees a failed request.
| Status | Message | Cause |
|---|---|---|
401 |
unauthorized |
No token was sent. |
401 |
invalid or revoked API token |
The token is unknown, expired or revoked. Revocation applies from the next request, initialize included. |
403 |
this token doesn't have the runs:logs scope ("Read step logs"), which this endpoint needs. Add it under API tokens, Edit scopes, and the same token works here |
The token lacks the tool’s scope, which the message names. A client gets this if it calls a tool that tools/list didn’t offer. |
403 |
you don't have permission to do that |
The token is pinned to a team its owner has left, or the owner’s role doesn’t allow the action. |
403 |
you can't run workflows in that namespace |
A run targets a namespace your team may not use. |
402 |
your plan doesn't let you use catalog steps: step "upload" uses catalog item "s3-upload". Production is the cheapest plan that does. A team owner can change the plan under Team settings, Billing. dagweave_get_entitlements shows everything your plan holds back ... |
Your plan lacks something the call needs, such as the audit log or a catalog item. The message names it, any steps that use it and the cheapest plan with it, then points at dagweave_get_entitlements and dagweave_ask_for_more. |
402 |
your plan doesn't include running workflows. Production is the cheapest plan that does. ... |
Your plan can’t run workflows. |
429 |
varies | You’re over the rate limit or a plan quota, such as monthly executions or workflow count. Any Retry-After and X-RateLimit-* headers are copied onto the MCP response. |
Everything else is HTTP 200 with isError: true and the reason in the text
block, so the agent can read it and retry.
| Text | Cause |
|---|---|
unknown argument "format" |
The tool doesn’t declare that argument. |
argument "limit" must be a integer |
The argument has the wrong type. |
argument "runId" is required |
A required argument is missing or empty. |
this Idempotency-Key was already used for a different request |
The agent reused a key for a new request. Send a fresh one. |
| The endpoint’s error | For example a 404 for a run or workflow that doesn’t exist or isn’t yours, a stale baseVersion, a draft with faults, or connector is offline (no recent heartbeat). Is it running? |
An unknown tool name gets JSON-RPC error -32602 with unknown tool <name>. An
unknown method gets -32601.