Connect a Server Workflow through MCP

Every Server-runnable projectType: "workflow" project exposes a standard Streamable HTTP MCP endpoint. Each entrypoint becomes one tool. Conversation and Kanban do not expose this endpoint.

Open the MCP page in a Workflow's Server Web project details to select draft, latest, or an exact version; copy the URL, Bearer header template, and generic client JSON; and inspect the tool catalog for that target. The page displays only <YOUR_API_KEY> and never reads or reveals a saved key.

Connection URL

https://workflow.example.com/api/workflows/<PROJECT_ID>/mcp?target=latest

Generic MCP client configuration:

{
  "mcpServers": {
    "workflow-11111111-1111-4111-8111-111111111111": {
      "url": "https://workflow.example.com/api/workflows/11111111-1111-4111-8111-111111111111/mcp?target=latest",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

MCP accepts only an account API Key or Server administrator Key in Authorization: Bearer. Browser cookie sessions, Embed tokens, Webhook secrets, and anonymous requests are rejected. An account Key still needs project run access and runs.create. Server rechecks authentication, project run access, and queue gates on every HTTP request and every tool call.

Targets and sessions

target	Session behavior
latest	Resolves to the exact online version at initialize time and remains fixed.
1.2.3	Remains fixed to that exact version.
draft	Pins the source revision read during initialize; a draft change invalidates the old session.

The initialize response returns Mcp-Session-Id. Every later POST, SSE GET, and DELETE must send that header with the same Bearer credential, project, and target. Sessions never retain the raw Key and expire after 30 minutes of inactivity by default. Expiration, DELETE, or Server shutdown cancels active calls. Reusing a session across credentials, projects, or targets returns 403.

The tool list remains fixed after connection. Reconnect and initialize again after a project or draft change, a new release, or entrypoint/parameter edits.

Tool arguments and files

Parameter types, required/default/static-option/date-format rules, and unknown-field rejection match local MCP. Server file parameters use { "id": "..." }; multiple files use an array of those objects. Do not send names, MIME types, paths, URLs, or Base64. Server rereads authoritative metadata by ID and verifies that the file belongs to the current project.

Upload binary content through the existing file API first:

curl --request POST \
  --header "Authorization: Bearer $WORKFLOW_API_KEY" \
  --header "Content-Type: application/octet-stream" \
  --data-binary @./spec.pdf \
  "https://workflow.example.com/api/workflows/$PROJECT_ID/files?fileName=spec.pdf&mimeType=application/pdf"

Use data[0].id from the response as the MCP tool argument:

{
  "prompt": "Review the specification",
  "document": {
    "id": "wf_0123456789abcdef"
  }
}

A missing ID, an ID owned by another project, or metadata that is not a server file fails with MCP InvalidParams.

Execution, interactions, and audit

Tool calls reuse Server's existing preflightRun, run queue, persisted runs, related projects, Server file storage, and submitUserInput. Every call creates a runId visible in run logs and records MCP session, tool, resume, and run audit events. The run-log source is mcp.

Clients with form elicitation support can continue the same runId through waiting_for_input or tool approval and handle consecutive questions. Without elicitation support, when pending input contains a file field, or when it contains an arbitrary array field without static options, the tool returns interaction_required, the runId, and a field summary. Nothing is automatically approved. Interactive multi-select fields need static options before a standard MCP form can resume them.

Successful text content and structuredContent both contain:

{
  "runId": "20260828-abcd",
  "status": "success",
  "entrypointId": "validate",
  "entrypointTitle": "Validate",
  "output": {}
}

Execution failure, a nonzero business errCode, cancellation, or timeout returns isError: true with a compact error. MCP never returns the full report, node details, stdout, stderr, or credentials. Invalid argument shapes use MCP InvalidParams; HTTP authentication failures use 401/403; failures after workflow execution begins are MCP tool errors.

The documentation site's Server API tab also generates MCP operations for every method, header, and HTTP response.