Skip to main content
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
{
  "_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
{
  "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
{
  "isError": false,
  "content": [
    { "type": "text", "text": "<output JSON>" },
    { "type": "text", "text": "The flow returned successfully..." }
  ],
  "structuredContent": {
    "output": {
      "approval_status": "approved",
      "approver": "[email protected]",
      "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
{
  "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
{
  "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
{
  "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
{
  "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"]
  }
}
  • Output is present only when the flow completes with results.
  • Status is always present and includes execution metadata.

​
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
{
  "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.

​
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