Skip to content

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 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.

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:

Terminal window
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Requires clusters:read. Your connectors with their status, version, last heartbeat and the namespaces each one serves. No arguments.

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.

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.

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": "..."}.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

POST /api/v1/mcp HTTP/1.1
Host: api.dagweave.com
Authorization: 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.

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.