Skip to content
Moira Documentation

MCP Agent Guide

This guide explains how AI agents use MCP Moira tools to execute workflows.

MCP Tools Overview

Section titled “MCP Tools Overview”

MCP Moira exposes these tools:

ToolPurpose
listList available workflows
startStart workflow execution
stepAdvance workflow with input
manageCRUD operations on workflows
sessionUser info and execution state
settingsUser settings
tokenUpload/download tokens
helpDocumentation

Basic Workflow Execution

Section titled “Basic Workflow Execution”

1. Start Workflow

Section titled “1. Start Workflow”
start({ workflowId: "task-breakdown-flow" })

Returns:

{
  "processId": "abc-123-def",
  "directive": "Break down the task into steps...",
  "completionCondition": "Task breakdown complete with 3+ steps",
  "inputSchema": {
    "type": "object",
    "properties": {
      "steps": { "type": "array" }
    },
    "required": ["steps"]
  }
}

2. Execute Step

Section titled “2. Execute Step”

After completing the work described in directive:

step({
  processId: "abc-123-def",
  input: {
    "steps": ["Step 1", "Step 2", "Step 3"]
  }
})

Returns next directive or completion status.

3. Continue Until Complete

Section titled “3. Continue Until Complete”

Repeat step() calls until workflow returns completion.

Response Format

Section titled “Response Format”

Every workflow step returns:

FieldDescription
processIdUUID for this execution, use in all step() calls
directiveWhat to do (the instruction)
completionConditionWhen you’re done (success criteria)
inputSchemaHow to structure your response (JSON Schema)

Understanding Directives vs Conditions

Section titled “Understanding Directives vs Conditions”

directive = WHAT to do completionCondition = WHEN you’re successfully done

Example:

  • directive: “Run all project tests”
  • completionCondition: “All tests pass (0 failures)”

The agent must:

  1. Execute the directive (run tests)
  2. Verify the completionCondition is met (check for 0 failures)
  3. Only then proceed with step()

Input Schema

Section titled “Input Schema”

When inputSchema is provided, your response must match the schema exactly.

Example schema:

{
  "type": "object",
  "properties": {
    "result": {
      "type": "string",
      "enum": ["pass", "fail"]
    },
    "evidence": {
      "type": "string"
    }
  },
  "required": ["result", "evidence"]
}

Valid response:

{
  "result": "pass",
  "evidence": "All 302 tests passed"
}
Section titled “Navigation Tools”

List Executions

Section titled “List Executions”
session({ action: "executions" })

Returns all active executions for current user with status, workflow ID, and notes.

Get Current Step

Section titled “Get Current Step”

Resume workflow after interruption:

session({ action: "current_step", executionId: "abc-123" })

Returns current directive without advancing the workflow.

Get Full Context

Section titled “Get Full Context”
session({ action: "execution_context", executionId: "abc-123" })

Returns execution state including context variables and history.

Execution Notes

Section titled “Execution Notes”

Track execution progress with notes:

start({ workflowId: "dev-flow", note: "Feature: auth system" })

Update note during execution via step() input:

step({
  processId: "abc-123",
  input: {
    "task_result": "done",
    "execution_note": "Step 3: Integration tests"
  }
})

Or via session tool:

session({
  action: "update-note",
  executionId: "abc-123",
  note: "Step 3: Integration tests"
})

Finding Workflows

Section titled “Finding Workflows”

List All Workflows

Section titled “List All Workflows”
list()

Search by Name

Section titled “Search by Name”
list({ search: "test" })

Filter by Visibility

Section titled “Filter by Visibility”
list({ visibility: "public", limit: 10 })

Common Patterns

Section titled “Common Patterns”

Start and Execute First Step

Section titled “Start and Execute First Step”
// 1. Start
start({ workflowId: "research" })
// → { processId: "xyz", directive: "...", ... }


// 2. Do work, then advance
step({ processId: "xyz", input: { findings: "..." } })
// → { directive: "next step...", ... }

Resume After Interruption

Section titled “Resume After Interruption”
// 1. Find your execution
session({ action: "executions" })
// → [{ executionId: "xyz", status: "waiting", ... }]


// 2. Get current step
session({ action: "current_step", executionId: "xyz" })
// → { directive: "...", completionCondition: "...", ... }


// 3. Continue
step({ processId: "xyz", input: { ... } })

Validation Errors

Section titled “Validation Errors”

If step() returns validation error, check:

  1. Field names - Must match schema exactly (case sensitive)
  2. Required fields - All required properties must be present
  3. Data types - String vs number vs boolean must match
  4. Enum values - Must be one of allowed values
Section titled “Related Documentation”