MCP Tools Reference

Moira exposes workflow orchestration capabilities through MCP tools. This reference documents all available tools with parameters, return values, and examples.

• list - List available workflow templates
• manage - Create, edit, or get workflow details
• start - Start new workflow execution
• step - Advance workflow with agent input

• session - Get user, executions, or step info
• settings - Manage user settings

• token - Generate upload/download tokens

• help - Get documentation and help

Lists all available workflow templates with validation status.

Parameters: None

Returns:

• Array of workflow objects with metadata
• Validation status for each workflow
• File paths and last modified timestamps

Example:

list()
→ [{ id: "example", name: "Example Workflow", valid: true, ... }]

Starts new workflow execution.

Parameters:

• workflowId (string, required) - ID of workflow to execute
• note (string, optional) - Short note to identify this execution (max 500 chars)
• parentExecutionId (string, required) - Parent execution ID for linking workflows. Use "none" for standalone workflows, or provide parent execution UUID to link child workflows

Returns:

• Process ID for tracking execution
• First agent directive with instructions
• Completion condition and input schema

Example:

start({ workflowId: "example", note: "Feature implementation task" })
→ { processId: "abc-123", directive: "...", ... }

Parent Execution Linking:

start({ workflowId: "sub-workflow", parentExecutionId: "parent-abc-123" })

When child workflow completes, system returns continuation info for the parent execution.

Advances workflow execution with agent input.

Parameters:

• processId (string, required) - Process ID from start
• input (any) - Agent response matching inputSchema

Returns:

• Next agent directive (if workflow continues)
• Completion status (if workflow finished)
• Updated context and state

Example:

step({
  processId: "abc-123",
  input: { result: "completed", confidence: 9 }
})
→ { directive: "Next task...", ... }

Magic Variable - execution_note:

When input contains execution_note field, it updates the execution’s note for tracking:

step({
  processId: "abc-123",
  input: { task_name: "Auth feature", execution_note: "Implementing OAuth" }
})

The updated note appears in execution lists (session({ action: "executions" })).

Unified tool for workflow CRUD operations.

Creates new workflow from JSON definition with validation.

Parameters:

• action: "create" (required)
• workflow (object, required) - Workflow definition
  • systemReminder (string, optional) - Per-workflow system reminder that overrides global setting
• overwrite (boolean, optional) - Allow overwriting existing workflow

Returns:

• Success status
• Workflow ID
• Validation results with errors/warnings

Example:

manage({
  action: "create",
  workflow: {
    id: "my-workflow",
    metadata: { name: "My Workflow", version: "1.0.0", description: "..." },
    nodes: [...]
  }
})
→ { success: true, workflowId: "my-workflow", validation: {...} }

Edits existing workflow with partial updates.

Parameters:

• action: "edit" (required)
• workflowId (string, required) - ID of workflow to edit
• changes (object, required) - Changes to apply
  • metadata - Update name, version, description
  • addNodes - Array of nodes to add
  • removeNodes - Array of node IDs to remove
  • updateNodes - Array of objects with nodeId and changes properties
  • systemReminder - Per-workflow system reminder (set to empty string to clear)

Returns:

• Success status
• Change summary
• Validation results

Example:

manage({
  action: "edit",
  workflowId: "my-workflow",
  changes: {
    metadata: { description: "Updated description" },
    addNodes: [{ type: "end", id: "new-end", ... }]
  }
})
→ { success: true, changesSummary: {...}, validation: {...} }

Retrieves workflow information with metadata and validation.

Parameters:

• action: "get" (required)
• workflowId (string, required) - ID of workflow to retrieve
• includeNodes (boolean, optional, default: true) - Include node definitions
• includeValidation (boolean, optional, default: true) - Include validation info
• offset (number, optional) - Pagination: starting node index
• limit (number, optional) - Pagination: number of nodes to return

Returns:

• Workflow metadata
• Structure analysis
• Nodes (if includeNodes=true)
• Validation status (if includeValidation=true)

Example:

manage({
  action: "get",
  workflowId: "my-workflow",
  includeNodes: true,
  includeValidation: true
})
→ { metadata: {...}, nodes: [...], validation: {...} }

Gets workflow structure (metadata + node graph) without full node content. Useful for understanding workflow layout.

Parameters:

• action: "get-structure" (required)
• workflowId (string, required) - ID of workflow to analyze
• graph (boolean, optional) - Include ASCII flow visualization
• detailed (boolean, optional) - Include directive previews for each node

Returns:

• Workflow metadata
• Node graph with connections
• ASCII visualization (if graph=true)
• Node previews (if detailed=true)

Example:

manage({ action: "get-structure", workflowId: "my-workflow", graph: true, detailed: true })
→ { metadata: {...}, graph: "start → step-1 → step-2 → end", nodesPreview: [...] }

Gets specific node by ID with full content.

Parameters:

• action: "get-node" (required)
• workflowId (string, required) - Workflow ID
• nodeId (string, required) - Node ID to retrieve

Returns:

• Full node definition
• Connections
• Input schema

Example:

manage({ action: "get-node", workflowId: "my-workflow", nodeId: "step-1" })
→ { id: "step-1", type: "agent-directive", directive: "...", ... }

Searches nodes by text in directive, completionCondition, or ID. Supports regex patterns.

Parameters:

• action: "search-nodes" (required)
• workflowId (string, required) - Workflow ID
• query (string, required) - Search text or regex pattern
• includeVariables (boolean, optional) - Search in workflow variables
• snippetMode (boolean, optional) - Return matched text with context only
• limit (number, optional) - Max results
• offset (number, optional) - Pagination offset

Returns:

• Array of matching nodes
• Match context (where text was found)
• Variable matches (if includeVariables=true)

Example:

manage({ action: "search-nodes", workflowId: "my-workflow", query: "validation", includeVariables: true, snippetMode: true })
→ { results: [{ nodeId: "validate-step", matches: ["directive"], snippet: "...run validation..." }] }

Validates workflow structure and returns errors/warnings.

Parameters:

• action: "validate" (required)
• workflowId (string, required) - Workflow ID

Returns:

• Validation status (valid/invalid)
• Errors array (blocking issues)
• Warnings array (non-blocking issues)

Example:

manage({ action: "validate", workflowId: "my-workflow" })
→ { valid: true, errors: [], warnings: ["Node 'old-step' is unreachable"] }

Lists all variables from workflow start node initialData.

Parameters:

• action: "list-variables" (required)
• workflowId (string, required) - Workflow ID

Returns:

• Variable count
• Array of variables with name, type, and preview

Example:

manage({ action: "list-variables", workflowId: "my-workflow" })
→ { variableCount: 3, variables: [{ name: "test_directive", type: "string", preview: "Run npm test" }] }

Gets specific variable value from workflow start node.

Parameters:

• action: "get-variable" (required)
• workflowId (string, required) - Workflow ID
• variableName (string, required) - Variable name

Returns:

• Variable name and value

Example:

manage({ action: "get-variable", workflowId: "my-workflow", variableName: "test_directive" })
→ { variableName: "test_directive", value: "Run npm test" }

Sets or creates variable in workflow start node initialData.

Parameters:

• action: "set-variable" (required)
• workflowId (string, required) - Workflow ID
• variableName (string, required) - Variable name
• variableValue (any, required) - Variable value

Returns:

• Old and new values
• Success message

Example:

manage({ action: "set-variable", workflowId: "my-workflow", variableName: "test_directive", variableValue: "Run npm test -- --coverage" })
→ { variableName: "test_directive", oldValue: "Run npm test", newValue: "Run npm test -- --coverage" }

Deletes variable from workflow start node initialData.

Parameters:

• action: "delete-variable" (required)
• workflowId (string, required) - Workflow ID
• variableName (string, required) - Variable name

Returns:

• Deleted value
• Success message

Example:

manage({ action: "delete-variable", workflowId: "my-workflow", variableName: "unused_var" })
→ { variableName: "unused_var", deletedValue: "old value" }

Compares two workflows and shows differences in metadata and nodes.

Parameters:

• action: "diff" (required)
• workflowId (string, required) - First workflow ID
• compareWorkflowId (string, required) - Second workflow ID to compare against

Returns:

• Metadata differences
• Added nodes (in second but not first)
• Removed nodes (in first but not second)
• Modified nodes with change details

Example:

manage({ action: "diff", workflowId: "workflow-v1", compareWorkflowId: "workflow-v2" })
→ { metadataDiff: { version: { old: "1.0.0", new: "2.0.0" } }, addedNodes: ["new-step"], removedNodes: [], modifiedNodes: [...] }

Creates a copy of existing workflow with new ID.

Parameters:

• action: "copy" (required)
• workflowId (string, required) - Source workflow ID
• newName (string, optional) - Name for copied workflow

Returns:

• New workflow ID
• Success status

Example:

manage({ action: "copy", workflowId: "template-workflow", newName: "My Copy" })
→ { newWorkflowId: "template-workflow-copy-123", success: true }

Gets compact list of workflow nodes without full content.

Parameters:

• action: "list-nodes" (required)
• workflowId (string, required) - Workflow ID
• typeFilter (string, optional) - Filter by node type
• includePreview (boolean, optional) - Include directive preview
• previewLength (number, optional) - Preview character limit

Returns:

• Node count
• Array of compact nodes (id, type, connections)

Example:

manage({ action: "list-nodes", workflowId: "my-workflow", typeFilter: "agent-directive" })
→ { nodeCount: 5, nodes: [{ id: "step-1", type: "agent-directive", connections: ["step-2"] }] }

Gets multiple nodes by ID array in single request.

Parameters:

• action: "get-nodes" (required)
• workflowId (string, required) - Workflow ID
• nodeIds (string[], required) - Array of node IDs

Returns:

• Found nodes
• Not found node IDs

Example:

manage({ action: "get-nodes", workflowId: "my-workflow", nodeIds: ["step-1", "step-2"] })
→ { foundCount: 2, nodes: [...], notFound: [] }

Analyzes variable sources and usages across workflow.

Parameters:

• action: "analyze-variables" (required)
• workflowId (string, required) - Workflow ID

Returns:

• Variable count
• Analysis with sources and usages per variable

Example:

manage({ action: "analyze-variables", workflowId: "my-workflow" })
→ { variableCount: 3, analysis: { "task_name": { sources: [...], usages: [...] } } }

Changes workflow visibility (public/private).

Parameters:

• action: "set-visibility" (required)
• workflowId (string, required) - Workflow ID
• visibility (string, required) - “public” or “private”

Returns:

• Previous and new visibility

Example:

manage({ action: "set-visibility", workflowId: "my-workflow", visibility: "public" })
→ { previousVisibility: "private", newVisibility: "public" }

Unified tool for session and execution information.

Get information about the currently authenticated user.

Parameters:

• action: "user" (required)

Returns:

• Email
• Name

Example:

session({ action: "user" })
→ { email: "user@example.com", name: "John" }

List active workflow executions for current user.

Parameters:

• action: "executions" (required)

Returns:

• Array of active execution objects
• Status, workflow ID, start time for each

Example:

session({ action: "executions" })
→ [{ executionId: "abc-123", workflowId: "example", status: "waiting", note: "Feature task", ... }]

Get full execution state including context variables.

Parameters:

• action: "execution_context" (required)
• executionId (string, required) - Execution ID to inspect

Returns:

• Execution status (running, waiting, completed, failed)
• Current node information
• Context variables
• Node execution history

Example:

session({ action: "execution_context", executionId: "abc-123" })
→ { status: "waiting", currentNodeId: "task-1", context: {...}, ... }

Repeats current workflow step without advancing execution.

Parameters:

• action: "current_step" (required)
• executionId (string, required) - ID of the execution to check

Returns:

• Current directive
• Completion condition
• Input schema
• Context information

Example:

session({ action: "current_step", executionId: "abc-123" })
→ { directive: "Complete task...", completionCondition: "...", inputSchema: {...} }

Updates execution note for easier identification in execution lists.

Parameters:

• action: "update-note" (required)
• executionId (string, required) - Execution ID to update
• note (string, required) - New note (max 500 chars)

Returns:

• Success status
• Updated execution ID and note

Example:

session({ action: "update-note", executionId: "abc-123", note: "Step 5: Integration tests" })
→ { success: true, executionId: "abc-123", note: "Step 5: Integration tests" }

Unified tool for user settings management.

Get user settings by category or all settings.

Parameters:

• action: "get" (required)
• category (string, optional) - Filter by category (telegram, ui, profile, etc.)

Returns:

• Settings object with values
• Encrypted fields shown as [encrypted]

Example:

settings({ action: "get", category: "ui" })
→ { "ui.theme": "dark", "ui.language": "en" }

Set user setting value with validation.

Parameters:

• action: "set" (required)
• key (string, required) - Setting key (e.g., ui.theme, telegram.bot_token)
• value (any, required) - Setting value

Returns:

• Success status
• Updated value (encrypted if applicable)

Example:

settings({
  action: "set",
  key: "ui.theme",
  value: "dark"
})
→ { success: true, key: "ui.theme", value: "dark" }

List available setting definitions.

Parameters:

• action: "list" (required)
• category (string, optional) - Category filter

Returns:

• Array of setting definitions with key and description

Example:

settings({ action: "list", category: "telegram" })
→ [{ key: "telegram.bot_token", description: "Your Telegram bot token" }]

Generate temporary tokens for large workflow file operations.

Generate token for uploading large workflows via HTTP.

Parameters:

• action: "upload" (required)
• ttlMinutes (number, optional, default: 60) - Token TTL in minutes

Returns:

• token - Upload token
• uploadUrl - Full URL for upload
• expiresAt - ISO 8601 expiration timestamp
• uploadInstructions - Upload details:
  • method: "POST"
  • contentType: "multipart/form-data"
  • fieldName: "workflow"
  • fileFormat: "JSON file with workflow definition"
  • example: curl command example

Upload Request:

curl -X POST "${uploadUrl}" -F "workflow=@your-workflow.json"

Example:

token({ action: "upload", ttlMinutes: 30 })
→ {
    token: "abc123",
    uploadUrl: "https://moiraqq.com/api/public/workflows/upload/abc123",
    expiresAt: "2024-01-15T12:00:00.000Z",
    uploadInstructions: {
      method: "POST",
      contentType: "multipart/form-data",
      fieldName: "workflow",
      fileFormat: "JSON file with workflow definition",
      example: "curl -X POST '...' -F 'workflow=@your-workflow.json'"
    }
  }

Generate token for downloading workflows.

Parameters:

• action: "download" (required)
• workflowId (string, required) - Workflow ID to download
• ttlMinutes (number, optional, default: 60) - Token TTL in minutes

Returns:

• Download token
• Download URL
• Expiration timestamp

Example:

token({
  action: "download",
  workflowId: "my-workflow",
  ttlMinutes: 30
})
→ { token: "abc123", downloadUrl: "https://.../download", expiresAt: "..." }

Get documentation and help for the workflow system.

Parameters:

• topic (string | string[], optional) - Help topic(s), single or array

Topics:

• overview, introduction - System overview
• quickstart - Getting started guide
• nodes - Node types reference
• workflows - Workflow structure
• templates - Template variables
• tools - This tools reference
• validation - Validation system
• claude-code - Claude Code integration
• mcp-clients - Other MCP clients
• examples - Pattern examples with code snippets
• pattern-* - Workflow patterns (e.g., pattern-workspace, pattern-skip)

Single Topic Example:

help({ topic: "nodes" })
→ "# Node Types\n\nMoira supports 7 node types..."

Multiple Topics Example:

help({ topic: ["pattern-workspace", "pattern-skip"] })
→ "# Workspace Pattern\n...\n\n---\n\n# Skip Pattern\n..."

Multiple topics are concatenated with separators for combined documentation lookup.

• MCP Agent Guide - How to use MCP tools
• Troubleshooting - Common issues