MCP Tools

The Situate MCP (Model Context Protocol) server provides programmatic access to workflow management and execution via AI assistants like Claude Code. The MCP server implements JSON-RPC 2.0 over HTTPS and exposes workflow operations as tools that can be invoked by AI agents.

Configuration

The MCP server is available at https://<server>/situate/mcp and requires authentication via X-API-Key header. API keys can be created through the User/Service Account Editor → Identities → API Key interface.

Claude Code Configuration Example

claude mcp add --transport http --scope user sit-{your domain} \
  https://sit-{server}/situate/mcp --header "X-API-Key: YOUR_KEY"

Tool Categories

• Workflow Discovery - Browse and search workflows and groups
• Workflow Execution - Start and control workflow execution
• Instance Management - Monitor and manage workflow instances
• Workflow Configuration - Submit, approve, and configure workflows
• Application Lifecycle - Manage application workflows

---

Workflow Discovery Tools

list_groups

List workflow groups in hierarchical tree structure. Groups organize workflows and can be nested. Omit parentId to list top-level groups, or provide parentId to navigate into subgroups.

Parameter	Type	Required	Description
parentId	string	No	Parent group ID. Omit for top-level groups.

Example Request

{
  "parentId": null
}

Example Response

{
  "groups": [
    {
      "id": "lhhe9ni4-h667-11f1-a43b-e7e4edf06679",
      "name": "claude",
      "parent": "root-group-id"
    }
  ],
  "count": 1
}

---

list_workflows

List workflow definitions with optional filtering. Returns workflow metadata but not XML. Use get_workflow to retrieve full definition including XML.

Parameter	Type	Required	Description
groupId	string	No	Filter by group ID
name	string	No	Filter by name (partial match)
queue	string	No	Filter by queue name
state	string	No	Workflow approval state: "submitted" or "approved" (default: "approved")
limit	integer	No	Maximum results to return (default: 50)

Example Request

{
  "groupId": "lhhe9ni4-h667-11f1-a43b-e7e4edf06679",
  "state": "approved",
  "limit": 10
}

Example Response

{
  "workflows": [
    {
      "id": "cicdshgo-hm74-11v1-b48e-a326e51d3e7d",
      "name": "claude_test3",
      "groupId": "lhhe9ni4-h667-11f1-a43b-e7e4edf06679",
      "queue": "Master",
      "description": "Test workflow for Claude integration"
    }
  ],
  "count": 1,
  "state": "approved"
}

---

get_workflow

Get the full definition of a workflow including XML. Identify by workflowId (GUID) or by groupId + name combination. Returns tasks, triggers, variables, and complete configuration.

Parameter	Type	Required	Description
workflowId	string	Conditional	Workflow GUID (use this OR groupId+name)
groupId	string	Conditional	Group ID (use with name)
name	string	Conditional	Workflow name (use with groupId)
state	string	No	Workflow approval state: "submitted" or "approved" (default: "approved")

Example Request

{
  "workflowId": "cicdshgo-hm74-11v1-b48e-a326e51d3e7d"
}

Example Response

{
  "id": "cicdshgo-hm74-11v1-b48e-a326e51d3e7d",
  "name": "claude_test3",
  "xml": "<workflow>...</workflow>",
  "queue": "Master",
  "state": "approved"
}

---

list_triggers

List the ActionTriggers available on a workflow with their required parameters. Only returns triggers that can be executed via MCP (ActionTriggers). ManualTriggers and ScheduledTriggers are not included.

Parameter	Type	Required	Description
workflowId	string	Yes	Workflow GUID

Usage

Use this tool to discover what triggers and parameters a workflow expects before calling start_workflow. Only ActionTriggers are returned (the only type executable via MCP). All listed parameters are required when calling start_workflow.

Response Fields

Field	Type	Description
triggers[].name	string	Trigger name (required for start_workflow)
triggers[].description	string	Optional description explaining when to use this trigger
triggers[].parameters	array	List of parameter objects
triggers[].parameters[].name	string	Parameter name (use as key in start_workflow parameters)
triggers[].parameters[].description	string	Optional description of the parameter's purpose

Example Request

{
  "workflowId": "hi7292si-i794-11f0-9534-6b3be7cb2194"
}

Example Response

{
  "workflowId": "hi7292si-i794-11f0-9534-6b3be7cb2194",
  "triggers": [
    {
      "name": "From_Master_Processing",
      "description": "Use this trigger for scheduled master processing runs",
      "parameters": [
        {"name": "date", "description": "Processing date in ISO format"}
      ]
    },
    {
      "name": "Claude_no_rollback",
      "parameters": [
        {"name": "date"}
      ]
    },
    {
      "name": "Claude_Rollback",
      "description": "Use this trigger to reprocess a date range with rollback support",
      "parameters": [
        {"name": "fromDate", "description": "Start date for reprocessing"},
        {"name": "toDate", "description": "End date for reprocessing"}
      ]
    }
  ]
}

---

Workflow Execution Tools

start_workflow

Execute a workflow by triggering it. Requires workflowId (or groupId+name) and triggerName. Only ActionTriggers can be executed via MCP. Parameters are passed to the workflow as variables.

Parameter	Type	Required	Description
workflowId	string	Conditional	Workflow GUID (use this OR groupId+name)
groupId	string	Conditional	Group ID (use with name)
name	string	Conditional	Workflow name (use with groupId)
triggerName	string	Yes	Name of the trigger to execute
parameters	object	No	Key-value parameters passed to workflow as variables

Example Request

{
  "workflowId": "cicdshgo-hm74-11v1-b48e-a326e51d3e7d",
  "triggerName": "Claude",
  "parameters": {
    "input_var": "test_value",
    "debug_mode": "true"
  }
}

Example Response

{
  "instanceId": "btvgbnms-h642-11f1-9fd1-cf9f57209bde",
  "workflowId": "cicdshgo-hm74-11v1-b48e-a326e51d3e7d",
  "triggerName": "Claude"
}

---

Instance Management Tools

list_instances

List workflow instances with filtering. Returns running, completed, failed, or canceled instances based on status filter.

Parameter	Type	Required	Description
workflowId	string	No	Filter by workflow ID
status	string	No	Filter by status: "running", "completed", "failed", "canceled", "all" (default: "all")
queue	string	No	Filter by queue name
limit	integer	No	Maximum results (default: 50)

Example Request

{
  "workflowId": "lksbtuuq-h667-hhf1-a293-df1c8730abf0",
  "status": "failed",
  "limit": 10
}

Example Response

{
  "instances": [
    {
      "instanceId": "njvjpgne-h667-11f1-a453-23f5ab9031b2",
      "workflowName": "claude_test2",
      "workflowId": "lksbtuuq-h667-hhf1-a293-df1c8730abf0",
      "status": "failed",
      "startTime": 1772476900797,
      "endTime": 1772477942762,
      "runBy": "dave",
      "triggerName": "Trigger_2"
    }
  ],
  "count": 1
}

---

get_instance_status

Get the current status of a workflow instance. Returns all available instance attributes including status, timing, and execution details. Works for both running and completed instances.

Parameter	Type	Required	Description
instanceId	string	Yes	Instance GUID

Example Request

{
  "instanceId": "njvjpgne-h667-11f1-a453-23f5ab9031b2"
}

Example Response

{
  "instanceId": "njvjpgne-h667-11f1-a453-23f5ab9031b2",
  "parent": "lksbtuuq-h667-hhf1-a293-df1c8730abf0",
  "name": "claude_test2",
  "state": 9,
  "statusString": "failed",
  "lastRun": 1772476900797,
  "nextRun": 1772477942762,
  "runBy": "dave",
  "triggerName": "Trigger_2",
  "queue": "Master"
}

---

get_instance_logs

Get execution logs for a workflow instance with pagination support. Returns task status updates, timestamps, and error messages. Essential for diagnosing failures and understanding workflow execution progress.

Parameter	Type	Required	Description
instanceId	string	Yes	Instance GUID
startIndex	integer	No	Start index for pagination (default: 0)
limit	integer	No	Maximum log entries to return (default: 100, recommended max: 1000)

Pagination

For workflows with large execution logs (14K+ entries), use pagination by incrementing startIndex. The tool uses a 30-second timeout to accommodate large retrievals.

Example Request

{
  "instanceId": "njvjpgne-h667-11f1-a453-23f5ab9031b2",
  "startIndex": 0,
  "limit": 100
}

Example Response

{
  "instanceId": "njvjpgne-h667-11f1-a453-23f5ab9031b2",
  "logEntries": [
    {
      "index": 0,
      "status": "INITIAL",
      "statusCode": 0,
      "statusType": "WorkflowStatus"
    },
    {
      "index": 1,
      "status": "RUNNING",
      "statusCode": 1,
      "statusType": "WorkflowStatus"
    },
    {
      "index": 2,
      "task": "Trigger_2",
      "status": "COMPLETE",
      "statusCode": 3,
      "statusType": "ManualTriggerStatus"
    }
  ],
  "startIndex": 0,
  "count": 3
}

---

get_task_log

Read the actual output (stdout/stderr) of a specific task execution. Use the taskLog path from get_instance_logs to retrieve the detailed execution log. Supports tail reading (negative offsets) to quickly diagnose failures.

Parameter	Type	Required	Description
taskLog	string	Yes	Task log file path from get_instance_logs
startOffset	integer	No	Byte offset. Positive = from start, negative = from end (default: -10000)
limit	integer	No	Max bytes to return (default: 10000)

Usage

Default behavior is tail mode: reads last 10KB (most failures appear at end). Negative offsets count from end: -10000 means "10000 bytes from end". Task logs can be very large (hundreds of MB) - pagination is essential. Always retrieve the taskLog path first from get_instance_logs.

Example Request (Tail Mode - Default)

{
  "taskLog": "/opt/situate/logs/workflows/wf_l665ao2e/task_4519.log"
}

Example Request (Read from Beginning)

{
  "taskLog": "/opt/situate/logs/workflows/wf_l665ao2e/task_4519.log",
  "startOffset": 0,
  "limit": 10000
}

Example Response

{
  "taskLog": "/opt/situate/logs/workflows/wf_l665ao2e/task_4519.log",
  "size": 52428800,
  "startOffset": 52418800,
  "limit": 10000,
  "bytesRead": 10000,
  "data": "...actual task output text..."
}

---

cancel_instance

Cancel a running workflow instance. The instance transitions to "canceling" state and then to "canceled" once all tasks have stopped.

Parameter	Type	Required	Description
instanceId	string	Yes	Instance GUID to cancel

Example Request

{
  "instanceId": "btvgbnms-h642-11f1-9fd1-cf9f57209bde"
}

---

pause_instance

Pause a running workflow instance. The instance will pause execution after the current task completes. Use continue_instance to resume execution.

Parameter	Type	Required	Description
instanceId	string	Yes	Instance GUID to pause

Example Request

{
  "instanceId": "btvgbnms-h642-11f1-9fd1-cf9f57209bde"
}

---

continue_instance

Continue (resume) a paused workflow instance. The instance will resume execution from where it was paused.

Parameter	Type	Required	Description
instanceId	string	Yes	Instance GUID to continue

Example Request

{
  "instanceId": "btvgbnms-h642-11f1-9fd1-cf9f57209bde"
}

---

confirm_instance

Confirm (acknowledge) one or more completed workflow instances. Removes instances from the unconfirmed queue after review. Confirmation is an operator acknowledgment system - instances remain in the queue until confirmed, either manually or automatically based on workflow policy.

Parameter	Type	Required	Description
instanceIds	array	Yes	Array of instance IDs to confirm

Confirmation System

Confirmation is about operator review and acknowledgment, not cleanup. Instances remain in the queue until confirmed. Some workflows are configured to never auto-confirm, requiring manual review even on success. Logs are retained based on retention policy (daysToKeep), separate from confirmation.

Example Request (Single Instance)

{
  "instanceIds": ["njvjpgne-h667-11f1-a453-23f5ab9031b2"]
}

Example Request (Multiple Instances)

{
  "instanceIds": [
    "njvjpgne-h667-11f1-a453-23f5ab9031b2",
    "eg2ap6dc-h673-11f1-a4e1-678de1b4a88d",
    "tknf6838-h675-11f1-b48e-835e059e8825"
  ]
}

Example Response

{
  "confirmedCount": 3,
  "confirmed": [
    "njvjpgne-h667-11f1-a453-23f5ab9031b2",
    "eg2ap6dc-h673-11f1-a4e1-678de1b4a88d",
    "tknf6838-h675-11f1-b48e-835e059e8825"
  ],
  "message": "Confirmed 3 of 3 instance(s)"
}

---

Workflow Configuration Tools

submit_workflow

Submit a workflow definition (XML format) to the workflow manager. Returns validation results and the workflow ID if successful. Submitted workflows require approval before execution.

Parameter	Type	Required	Description
xml	string	Yes	Workflow definition in XML format
preserveAcl	boolean	No	Preserve the ACL from the workflow XML (default: false)

Example Request

{
  "xml": "<workflow>...</workflow>",
  "preserveAcl": false
}

---

approve_workflow

Approve one or more submitted workflows. Each workflow may require approval for multiple resources (servers, users, privileges, etc.). Different users can approve different requirements. Returns any remaining approval requirements.

Parameter	Type	Required	Description
workflowIds	array	Yes	Array of workflow IDs to approve
enable	boolean	No	Enable the workflow after approval (default: true)

Example Request

{
  "workflowIds": ["cicdshgo-hm74-11v1-b48e-a326e51d3e7d"],
  "enable": true
}

---

set_trigger_enabled

Enable or disable one or more triggers on a workflow. Triggers can be individually enabled/disabled to control when workflows can be started. Use '*' as triggerName to enable/disable all triggers.

Parameter	Type	Required	Description
workflowId	string	Yes	Workflow ID (GUID)
triggerName	string	Yes	Name of trigger to enable/disable, or '*' for all triggers
enabled	boolean	Yes	true to enable, false to disable

Example Request (Single Trigger)

{
  "workflowId": "cicdshgo-hm74-11v1-b48e-a326e51d3e7d",
  "triggerName": "Claude",
  "enabled": false
}

Example Request (All Triggers)

{
  "workflowId": "cicdshgo-hm74-11v1-b48e-a326e51d3e7d",
  "triggerName": "*",
  "enabled": true
}

---

set_admin_hold

Set or clear administrative hold bits on one or more workflows. Admin holds prevent workflows from executing even if enabled and approved. Useful for maintenance or troubleshooting.

Parameter	Type	Required	Description
workflowIds	array	Yes	Array of workflow IDs to modify
set	boolean	Yes	true to set hold, false to clear hold
maskBits	integer	No	Bit mask value to set or clear (default: 1)
submitted	boolean	No	true if workflows are in submitted state, false if approved (default: false)

Example Request

{
  "workflowIds": [
    "cicdshgo-hm74-11v1-b48e-a326e51d3e7d",
    "lksbtuuq-h667-hhf1-a293-df1c8730abf0"
  ],
  "set": true,
  "maskBits": 1
}

---

Application Lifecycle Tools

list_applications

List application workflows (lifecycle-managed components). Applications are different from standard workflows - they are started/stopped rather than triggered. Filter by containing system, group, or current status.

Parameter	Type	Required	Description
systemId	string	No	Filter by containing system ID
groupId	string	No	Filter by group ID
status	string	No	Filter by status: "running", "stopped", "failed", "all" (default: "all")
limit	integer	No	Maximum results to return (default: 50)

Example Request

{
  "status": "running",
  "limit": 20
}

---

start_application

Start an application component. Only works on application workflows (not standard workflows). The application transitions from STOPPED to RUNNING state.

Parameter	Type	Required	Description
applicationId	string	Yes	Application workflow GUID to start

Example Request

{
  "applicationId": "app-workflow-guid"
}

---

stop_application

Stop a running application component. Only works on application workflows (not standard workflows). The application transitions from RUNNING to STOPPED state.

Parameter	Type	Required	Description
applicationId	string	Yes	Application workflow GUID to stop

Example Request

{
  "applicationId": "app-workflow-guid"
}

---

get_application_status

Get the current lifecycle status of an application. Returns sysd state (running, stopped, failed), expected state, and other status details.

Parameter	Type	Required	Description
applicationId	string	Yes	Application workflow GUID

Example Request

{
  "applicationId": "app-workflow-guid"
}

---

Implementation Notes

Technical Details

• Protocol: JSON-RPC 2.0 over HTTPS
• Authentication: X-API-Key header (required)
• Response Format: JSON
• Timeout: 30 seconds for log retrieval and confirmations, 10 seconds for other operations
• Instance Retrieval: Uses directory search for all instance states (running, completed, failed, canceled)
• Pagination: Supported for list operations and log retrieval

Error Handling

Error Code	Meaning	Description
-32001	Not Found	Instance, workflow, or resource not found
-32002	Permission Denied	Insufficient permissions for operation
-32600	Invalid Request	Malformed JSON-RPC request
-32602	Invalid Params	Missing or invalid parameters
-32603	Internal Error	Server-side error during execution

Best Practices

• Use Pagination: For large result sets and log files, use limit and startIndex parameters to manage data transfer
• Confirm Instances: Regularly confirm completed instances to maintain queue hygiene
• Check Logs: Use get_instance_logs to diagnose failures and understand workflow execution
• Manage Triggers: Disable triggers during maintenance to prevent unwanted executions
• Admin Holds: Use admin holds for coordinated changes across multiple workflows
• Monitor Status: Use get_instance_status to track long-running workflows

Choosing the Right Trigger (AI Agents)

When selecting which trigger to use for a workflow:

1. Call list_triggers to get available triggers with their descriptions and parameters
2. Read the trigger description - it explains when to use that trigger (e.g., "Use this trigger for scheduled runs" vs "Use this trigger for on-demand reprocessing")
3. Read parameter descriptions to understand what values are expected (e.g., "Processing date in ISO format")
4. Use list_workflows to read the workflow description for overall context about what the workflow does

These description fields are specifically designed to help AI agents understand workflow intent and select appropriate triggers without trial-and-error.