Skip to content
Moira Documentation

Quick Start

This guide helps you connect Moira to your AI client and run your first workflow.

Prerequisites

  • An MCP-compatible AI client (see supported clients below)
  • Moira account (sign up at Moira)

Setup

  1. Get your MCP endpoint

    For Moira Cloud: https://moira-mcp.com/mcp

    For self-hosted, use your server’s MCP endpoint.

  2. Configure your AI client

Recommended: Use CLI command

Terminal
claude mcp add --transport http moira https://moira-mcp.com/mcp

Then authenticate:

OAuth Flow
# After adding, authenticate within claude
/mcp
# → Select "moira"
# → Click "Authenticate"
# → Browser opens for OAuth
Alternative: Manual JSON config
{
  "mcpServers": {
    "moira": {
      "url": "https://moira-mcp.com/mcp"
    }
  }
}
Authentication without OAuth

For CI/CD, Docker, or environments without a browser — use an API token instead of OAuth.

1. Log in to Moira web UI → Settings → API Tokens
2. Create a token (starts with moira_)
3. Replace moira_YOUR_TOKEN below with your token
~/.config/claude/mcp.json
{
  "mcpServers": {
    "moira": {
      "url": "https://moira-mcp.com/mcp",
      "headers": {
        "Authorization": "Bearer moira_YOUR_TOKEN"
      }
    }
  }
}

  1. Authenticate the MCP server

    After adding the server configuration, complete OAuth authentication. Most clients will prompt you automatically or have an “Authenticate” button.

    No OAuth support?

    If your client cannot open a browser for OAuth, create an API token instead:

    1. Log in to Moira web UI → Settings → Apps & tokens → API tokens
    2. Create a token and copy it (starts with moira_)
    3. Add it as Authorization: Bearer moira_... header in your client config

    See MCP Clients → API Tokens for details.

  2. Verify connection

    Ask your AI client to list available Moira workflows:

    List available Moira workflows

    You should see a list of workflows you have access to.

  3. Run your first flow

    Ask your agent, in plain words, to run the first learning example on any small task:

    Use Moira to run Example 1: Simple Steps for this task: rename the file notes.txt to todo.txt

    The agent starts moira/example-simple-steps and goes through its four steps — understand the task, do it, check the result, report — one at a time; Moira hands it each step and checks its answer before the next. Open Workflows in the web app and choose the example to see the same steps as a simple diagram.

    From here on you do not have to name flows at all. Describe what you need, and your agent picks a ready flow or builds one for the task. The tutorial walks through all three learning examples; Which ready flow to use explains the everyday ones.

    Want a guided tour of the catalog?

    Say Start user onboarding flow. The interactive onboarding reads your current authorized public catalog, explains how the flows differ, records one exact workflow such as moira/test-planning, and starts it only if you choose to; deferring changes nothing.

Available MCP Tools

The core execution lifecycle uses these Moira tools:

ToolDescription
listList authorized workflows with pagination
startPrepare or execute a standalone or parent-linked start
stepSubmit a verified step result and get the next directive
sessionInspect and resume workflow executions
helpGet Moira documentation and help

Moira also exposes workflow management, settings, notes, artifacts, locks, reconciliation, and large-file token operations. See the MCP tools reference for the complete current catalog, exact input schemas, supported actions, and examples.

Example Session

Here’s what a typical workflow session looks like:

Agent: I'll start the full development workflow.
       [calls start with workflowId: "moira/software-development-flow"
        and parentExecutionId: "none"]


Moira: Process ID: 123e4567-e89b-42d3-a456-426614174000
       Step attempt ID: 11111111-1111-4111-8111-111111111111
       Your next task: Analyze the requirements document...
       Success criteria: Requirements are documented...


Agent: [analyzes requirements, produces output]
       [calls step with the exact Process ID, current Step attempt ID,
        and schema-valid evidence]


Moira: Process ID: 123e4567-e89b-42d3-a456-426614174000
       Step attempt ID: 22222222-2222-4222-8222-222222222222
       Your next task: Create implementation plan...
       Success criteria: Plan covers all requirements...


[... workflow continues until completion]

Next Steps