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

Get your MCP endpoint
For Moira Cloud: https://moira.witqq.ru/mcp
For self-hosted, use your server’s MCP endpoint.

Configure your AI client

Recommended: Use CLI command

Terminal

claude mcp add --transport http moira https://moira.witqq.ru/mcp

Then authenticate:

OAuth Flow

# After adding, authenticate within claude
/mcp
# → Select "moira"
# → Click "Authenticate"
# → Browser opens for OAuth

Alternative: Manual JSON config

# Alternative: Manual JSON config
# ~/.config/claude/mcp.json
{
  "mcpServers": {
    "moira": {
      "type": "http",
      "url": "https://moira.witqq.ru/mcp"
    }
  }
}

# Then: /mcp → Authenticate

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.witqq.ru/mcp",
      "headers": {
        "Authorization": "Bearer moira_YOUR_TOKEN"
      }
    }
  }
}

Recommended: Config file

~/.copilot/mcp-config.json

# ~/.copilot/mcp-config.json
{
  "mcpServers": {
    "moira": {
      "type": "http",
      "url": "https://moira.witqq.ru/mcp"
    }
  }
}

Then authenticate:

OAuth Flow

# After saving the config:
# 1. Start a Copilot CLI session
# 2. Type /mcp
# 3. Select "moira" → Authenticate
# → Browser opens for OAuth

Alternative: Interactive setup

# In Copilot CLI:
/mcp
# → Click "Add server"
# → Enter server URL
# → Complete OAuth

# Project-level config:
# .copilot/mcp-config.json (same format)

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

~/.copilot/mcp-config.json

{
  "mcpServers": {
    "moira": {
      "type": "http",
      "url": "https://moira.witqq.ru/mcp",
      "headers": {
        "Authorization": "Bearer moira_YOUR_TOKEN"
      }
    }
  }
}

Recommended: One-click install

Add to Cursor

Then authenticate:

OAuth Flow

# After clicking the button:
# 1. Cursor opens with install prompt
# 2. Click "Install" to add moira MCP server
# 3. Settings → MCP Servers → Find "moira"
# 4. Click "Authenticate" → Browser opens for OAuth

Alternative: Manual JSON config

~/.cursor/mcp.json

# ~/.cursor/mcp.json
{
  "mcpServers": {
    "moira": {
      "url": "https://moira.witqq.ru/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

~/.cursor/mcp.json

{
  "mcpServers": {
    "moira": {
      "url": "https://moira.witqq.ru/mcp",
      "headers": {
        "Authorization": "Bearer moira_YOUR_TOKEN"
      }
    }
  }
}

Desktop app: GUI method

Settings → Connectors

# In Claude Desktop app:

# 1. Open Settings (⌘+,)
# 2. Go to "Connectors" tab
# 3. Click "Add custom connector"
# 4. Enter:
#    Server URL: https://moira.witqq.ru/mcp
# 5. Click "Connect"
# 6. Browser opens → OAuth → Done

# No file editing

Recommended: One-click install

Add to VS Code

Then authenticate:

OAuth Flow

# After clicking the button:
# 1. VS Code opens with install prompt
# 2. Click "Install" to add moira MCP server
# 3. Settings → MCP Servers → Find "moira"
# 4. Click "Authenticate" → Browser opens for OAuth

Alternative: Manual configuration

settings.json

# Install MCP extension:
# ext install mcp-connector

# Then in settings.json:
{
  "mcp.servers": {
    "moira": {
      "url": "https://moira.witqq.ru/mcp",
      "transport": "http"
    }
  }
}

# Or: Command Palette → "MCP: Add Server"

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

settings.json

{
  "mcpServers": {
    "moira": {
      "url": "https://moira.witqq.ru/mcp",
      "headers": {
        "Authorization": "Bearer moira_YOUR_TOKEN"
      }
    }
  }
}

claude.ai - Browser chat (most popular)

Settings → Connectors

# On claude.ai (Pro/Max/Team/Enterprise):

# 1. Go to Settings → Connectors
# 2. Click "Add custom connector"
# 3. Enter:
#    Server URL: https://moira.witqq.ru/mcp
# 4. Click "Connect"
# 5. Complete OAuth authentication in browser
# 6. Tools appear in chat

# Requires paid plan

chat.openai.com - Browser chat

Settings → Connectors

# On chat.openai.com (Plus/Pro required):

# 1. Profile → Settings
# 2. Go to "Connectors" or "Integrations"
# 3. Click "Add connector"
# 4. Enter:
#    Name: MCP Moira
#    URL: https://moira.witqq.ru/mcp
# 5. Complete OAuth authentication
# 6. Tools available in chat

# Free tier doesn't support MCP

Mac app: With helper

Settings → Connectors

# Perplexity Mac App:

# 1. Install PerplexityXPC helper first:
#    Settings → Connectors → Install Helper
# 2. Click "Add Connector"
# 3. Enter:
#    Server Name: moira
#    Command: npx
#    Args: -y mcp-remote https://moira.witqq.ru/mcp
# 4. Complete OAuth authentication
# 5. Ask Perplexity to use MCP Moira tools

# Paid plan recommended

VS Code extension: Open-source AI assistant

config.yaml

# Continue extension in VS Code:

# 1. Install Continue extension
# 2. Open config: Ctrl+Shift+P → "Continue: Open config"
# 3. Add to config.yaml:
#
# mcp:
#   servers:
#     moira:
#       url: https://moira.witqq.ru/mcp
#       transport: http
#
# 4. Restart VS Code
# 5. Authenticate when prompted

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.yaml

mcpServers:
  - name: moira
    url: https://moira.witqq.ru/mcp
    headers:
      Authorization: "Bearer moira_YOUR_TOKEN"

Fast code editor with AI features

~/.config/zed/settings.json

# Zed editor:

# 1. Open Settings (⌘+,)
# 2. Add to settings.json under context_servers:
#
# "context_servers": {
#   "moira": {
#     "url": "https://moira.witqq.ru/mcp"
#   }
# }
#
# 3. Restart Zed
# 4. Authenticate when prompted

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/zed/settings.json

{
  "context_servers": {
    "moira": {
      "url": "https://moira.witqq.ru/mcp",
      "headers": {
        "Authorization": "Bearer moira_YOUR_TOKEN"
      }
    }
  }
}

Google AI terminal assistant

~/.gemini/settings.json

# Gemini CLI:

# 1. Edit ~/.gemini/settings.json:
#
# "mcpServers": {
#   "moira": {
#     "httpUrl": "https://moira.witqq.ru/mcp"
#   }
# }
#
# 2. Run: gemini auth
# 3. Complete OAuth flow

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

~/.gemini/settings.json

{
  "mcpServers": {
    "moira": {
      "httpUrl": "https://moira.witqq.ru/mcp",
      "headers": {
        "Authorization": "Bearer moira_YOUR_TOKEN"
      }
    }
  }
}

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 → 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.
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.
Start the user onboarding
Now simply type in the chat:
```
Start user onboarding flow
```
The agent will guide you through an interactive onboarding experience that:
- Explains Moira by demonstrating a workflow in action
- Shows you key workflows available
- Helps you get started with your first real task
This is the recommended way to learn Moira!

Available MCP Tools

Once connected, your AI client has access to these Moira tools:

Tool	Description
`list_workflows`	List available workflows
`start_workflow`	Start a new workflow execution
`execute_step`	Submit step result and get next directive
`get_help`	Get documentation and help
`manage_settings`	Manage user settings

Example Session

Here’s what a typical workflow session looks like:

Agent: I'll start the development workflow.
       [calls start_workflow with workflowId: "development-flow"]

Moira: Process ID: abc-123
       Your next task: Analyze the requirements document...
       Success criteria: Requirements are documented...

Agent: [analyzes requirements, produces output]
       [calls execute_step with processId: "abc-123" and result]

Moira: Process ID: abc-123
       Your next task: Create implementation plan...
       Success criteria: Plan covers all requirements...

[... workflow continues until completion]

Next Steps

Workflows - Understand workflow structure
Claude Code Integration - Detailed Claude Code setup
MCP Clients - Other MCP client integrations