> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running agentic workflows with MCP (Public Preview)

This document provides a technical overview of how the Model Context Protocol (MCP) integrates with the flow execution environment. The integration shows flows as standardized tools that can be discovered, started, and managed by MCP‑compatible clients. The design supports synchronous and asynchronous execution, human‑in‑the‑loop interaction through elicitation, and session‑aware operation.

MCP automatically publishes each flow as a set of tools with explicit schemas for inputs and outputs. Tool contracts standardize discovery and invocation. Registration requires a Watson Orchestrate endpoint and an access token that is derived from an API key. The token has a limited validity period and must be refreshed to maintain connectivity.

## Capabilities

* Dynamic tool discovery: Each flow model is shown as multiple MCP tools for synchronous execution, asynchronous execution, and status queries.
* Resilient session management: Multi‑session design supports reconnection and cleanup.
* Flexible execution: Synchronous (wait for completion) and asynchronous (claim‑check) patterns.
* Protocol compliance: MCP over Streamable HTTP transport.
* Security: User‑based authorization for all operations.

## Overview

* Tool discovery: Dynamic registration of tools per flow model (synchronous, asynchronous, query) and management tools.
* Management tools: subscribe\_flow, replay\_flow\_pending\_elicitation, submit\_flow\_elicitation, list\_flows, cancel\_flow.

## Tool registration

The Flow MCP server provides three tools per flow model to support distinct execution patterns. Draft and versioned models obtain separate tools.

Naming convention:

* Draft (latest): `run_flow_<model_name>`
* Specific version: `run_flow_<model_name>_<version>`

Tool metadata Each tool includes a \_meta section for lifecycle management:

```JSON json [expandable] theme={null}
{
  "_meta": {
    "model_id": "string",
    "version": "string",
    "model_name": "string",
    "kind": "string"
  }
}
```

### Tool 1 Synchronous flow execution (`run_flow__<model_name>`)

Runs a flow and waits for completion or interruption:

```JSON json [expandable] theme={null}
{
  "name": "run_flow__purchase_approval",
  "description": "Process a purchase approval request through the approval workflow",
  "inputSchema": {
    "type": "object",
    "properties": {
      "item": { "type": "string", "title": "Item Name" },
      "amount": { "type": "number", "title": "Amount" },
      "justification": { "type": "string", "title": "Justification" },
      "_context": {
        "type": "object",
        "description": "Optional context parameters for flow execution",
        "properties": {
          "thread_id": { "type": "string", "description": "Agent thread ID" },
          "environment_id": { "type": "string", "enum": ["draft", "live"], "description": "Execution environment" },
          "channel_id": { "type": "string", "description": "Request channel" },
          "channel_capabilities": { "type": "array", "items": { "type": "string" } },
          "agent_id": { "type": "string", "description": "Initiating agent ID" },
          "agent_version": { "type": "number", "description": "Caller agent version" }
        }
      }
    },
    "required": ["item", "amount"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "output": {
        "type": "object",
        "properties": {
          "approval_status": { "type": "string", "enum": ["approved", "rejected"] },
          "approver": { "type": "string" },
          "comments": { "type": "string" }
        }
      },
      "status": {
        "type": "object",
        "properties": {
          "instance_id": { "type": "string", "description": "Flow run ID" },
          "name": { "type": "string", "description": "Flow name" },
          "state": { "type": "string", "enum": ["working","input_required","completed","failed"], "description": "Run state" },
          "created_at": { "type": "string", "description": "ISO 8601 create time" },
          "updated_at": { "type": "string", "description": "ISO 8601 last update time" }
        },
        "required": ["instance_id", "state"]
      }
    },
    "required": ["status"]
  }
}
```

#### Behavior

* Runs to completion or returns on user input.
* Always returns status; includes output only on successful completion with results.
* Elicitations are issued automatically when user input is required.

Response examples for flows that complete with output:

```JSON json [expandable] theme={null}
{
  "isError": false,
  "content": [
    { "type": "text", "text": "<output JSON>" },
    { "type": "text", "text": "The flow returned successfully..." }
  ],
  "structuredContent": {
    "output": {
      "approval_status": "approved",
      "approver": "manager@example.com",
      "comments": "Approved"
    },
    "status": {
      "instance_id": "abc-123",
      "name": "purchase_approval",
      "state": "completed",
      "created_at": "2024-01-01T12:00:00.000Z",
      "updated_at": "2024-01-01T12:05:00.000Z"
    }
  }
}
```

Return for input:

```JSON json [expandable] theme={null}
{
  "isError": false,
  "content": [
    { "type": "text", "text": "The flow is waiting for user input..." }
  ],
  "structuredContent": {
    "status": {
      "instance_id": "abc-123",
      "name": "purchase_approval",
      "state": "input_required",
      "created_at": "2024-01-01T12:00:00.000Z",
      "updated_at": "2024-01-01T12:03:00.000Z"
    }
  }
}
```

### Tool 2 Asynchronous flow execution (`run_flow_async__<model_name>`)

Starts a flow and returns immediately with an instance\_id (claim‑check pattern).

Specification:

```JSON json [expandable] theme={null}
{
  "name": "run_flow_async__purchase_approval",
  "description": "Process a purchase approval request (async)",
  "inputSchema": {
    "type": "object",
    "properties": {
      "item": { "type": "string" },
      "amount": { "type": "number" },
      "justification": { "type": "string" },
      "_context": { }
    },
    "required": ["item", "amount"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "instance_id": { "type": "string", "description": "Started flow instance ID" }
    },
    "required": ["instance_id"]
  }
}
```

#### Behavior

* Starts execution in the background and returns instance\_id.
* Elicitations are issued when user input is required.
* Clients query status through `query_flow__<model_name>`.

Response:

```JSON json [expandable] theme={null}
{
  "isError": false,
  "content": [
    { "type": "text", "text": "Flow started" }
  ],
  "structuredContent": {
    "instance_id": "flow-abc123-def456"
  }
}
```

### Tool 3 Flow status query (`query_flow__<model_name>`)

Retrieves the status and output (if available) for a flow instance.

Specification:

```JSON json [expandable] theme={null}
{
  "name": "query_flow__purchase_approval",
  "description": "Query status and output by instance ID",
  "inputSchema": {
    "type": "object",
    "properties": {
      "instance_id": { "type": "string", "description": "Flow run ID" }
    },
    "required": ["instance_id"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "output": {
        "type": "object",
        "properties": {
          "approval_status": { "type": "string", "enum": ["approved", "rejected"] },
          "approver": { "type": "string" },
          "comments": { "type": "string" }
        }
      },
      "status": {
        "type": "object",
        "properties": {
          "instance_id": { "type": "string" },
          "name": { "type": "string" },
          "state": { "type": "string", "enum": ["working","input_required","completed","failed"] },
          "created_at": { "type": "string" },
          "updated_at": { "type": "string" }
        },
        "required": ["instance_id", "name", "state", "created_at", "updated_at"]
      }
    },
    "required": ["status"]
  }
}
```

<Note>
  * Output is present only when the flow completes with results.
  * Status is always present and includes execution metadata.
</Note>

## Context Parameters

An optional \_context object is available for callers to pass in more context, for example, `thread_id`, `environment_id`, `channel_id`, `agent_id`, `agent_version`. For the moment, only `thread_id` (the wxO message `thread_id`) and `environement_id` ('draft' or 'live') are used.

## Elicitation Handling

When a flow requires user input, an elicitation request is automatically issued to the MCP client. The client must respond within the timeout period to continue flow execution.

### Timeout behavior

* Elicitations timeout after **5 minutes** by default.
* When a timeout occurs, the elicitation request fails with a timeout error.

### Recovery from timeout

1. If an elicitation times out, note the elicitation ID from the original request.
2. Collect the user's response.
3. Call `submit_flow_elicitation` with the elicitation ID and response data.
4. The flow resumes execution with the provided input.

Example:

```JSON json [expandable] theme={null}
{
  "instance_id": "flow-abc123-def456",
  "elicitation_id": "task-789",
  "response": {
    "action": "accept",
    "content": {
      ... response data ...
    }
  }
}
```

## Dynamic tool lifecycle management

The server updates tool registrations in response to flow model events (create, update, delete, activate, deactivate).

### Lifecycle states

* Active: Tools available and executable.
* Deactivated: Tools that are registered but marked unavailable.
* Deleted: Tools registered but marked deleted.

#### Behavior

* Tools are marked as \[DEACTIVATED] or \[DELETED] in descriptions when flows are not runnable.
* Clients are notified through notifications/tools/list\_changed when tool availability changes.

## Execution patterns

### Synchronous

* Use `run_flow__<flow_name>`.
* Suitable for short‑running flows.
* Returns status and, when available, output.
* If user input is required, returns input\_required and issues elicitation; continue through the background then query with `query_flow__<flow_name>`.

### Asynchronous (claim‑check)

* Use `run_flow_async__<flow_name>`.
* Returns instance\_id immediately; query with `query_flow__<flow_name>`.
* Elicitations are issued as needed; execution continues in the background.

## Authorization model

* Identity: Each request is associated with an authenticated principal.
* Ownership: Initiators can list, query, subscribe to, replay elicitations for, and cancel their own flow instances.
* Session binding: Operations are validated per session.
* Operation checks: Authorization is evaluated for each action (subscribe\_flow, replay\_flow\_pending\_elicitation, submit\_flow\_elicitation, list\_flows, cancel\_flow).

## Session management

Unique session IDs per MCP client and clean up on disconnect.

## MCP Context Forge support

The flow MCP server is compatible with MCP Context Forge for enhanced context management and orchestration. Current Context Forge clients do not support MCP elicitations; human‑in‑the‑loop features are not available through that path. For more information see, [MCP context forge](https://github.com/IBM/mcp-context-forge).

## Connecting to Flow MCP Server

To connect to the Flow MCP server as a remote MCP endpoint, obtain the Watson Orchestrate API endpoint for your instance (`https://api.<hostname>/instances/<tenant_id>`) and append `/v1/orchestrate/flows/mcp`. Generate an access token from an API key that uses the documented process and provide it during registration. The access token has a limited validity period, refresh and reregister when it expires.

## References

* [MCP Specification](https://github.com/modelcontextprotocol/specification).