MCP Clients Integration

Moira works with any client that supports the Model Context Protocol (MCP). This guide covers setup for 11 popular MCP clients.

MCP Protocol Overview

Moira exposes tools via MCP over HTTP/SSE:

Endpoint: https://moira.witqq.ru/mcp
Transport: HTTP with SSE for streaming
Authentication: OAuth 2.0 or API Token

Client Configuration

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"
      }
    }
  }
}

Custom Client

For custom MCP client implementations, use the MCP SDK with URL: https://moira.witqq.ru/mcp

Available Tools

All MCP clients have access to these tools:

Workflow Management

Tool	Parameters	Description
`list_workflows`	-	List available workflows
`start_workflow`	`workflowId`	Start workflow execution
`execute_step`	`processId`, `input`	Submit step result

Session Management

Tool	Parameters	Description
`get_session_info`	`action`	Get session/execution info
`get_execution_context`	`executionId`	Get execution context

Help & Settings

Tool	Parameters	Description
`get_help`	`topic` (optional)	Get documentation
`manage_settings`	`action`, `key`, `value`	Manage settings

Authentication

Moira supports two authentication methods:

OAuth 2.0 (Default)

Client initiates connection to MCP endpoint 2. Server returns authentication required response
Client opens browser for OAuth flow 4. User authenticates with Moira 5. Client receives access token 6. Subsequent requests include token

API Tokens

For MCP clients that do not support OAuth (custom scripts, CI/CD pipelines, headless environments), use API tokens:

Log in to Moira web UI 2. Go to Settings → API Tokens 3. Click Create Token, enter a name and expiration 4. Copy the token (shown once, starts with moira_) 5. Configure your client with the token as Bearer authorization

Example configuration for a custom MCP client:

{
  "mcpServers": {
    "moira": {
      "url": "YOUR_MCP_ENDPOINT",
      "headers": {
        "Authorization": "Bearer moira_your_token_here"
      }
    }
  }
}

Tool Call Examples

List Workflows

{
  "method": "tools/call",
  "params": {
    "name": "list_workflows",
    "arguments": {}
  }
}

Start Workflow

{
  "method": "tools/call",
  "params": {
    "name": "start_workflow",
    "arguments": {
      "workflowId": "development-flow"
    }
  }
}

Execute Step

{
  "method": "tools/call",
  "params": {
    "name": "execute_step",
    "arguments": {
      "processId": "abc-123",
      "input": {
        "result": "Task completed successfully",
        "details": { "files": ["main.ts", "utils.ts"] }
      }
    }
  }
}

Error Handling

Common error responses:

Error	Cause	Solution
`UNAUTHORIZED`	Invalid/expired token	Re-authenticate
`NOT_FOUND`	Invalid workflow/process ID	Verify IDs
`FORBIDDEN`	No access to resource	Check permissions
`VALIDATION_ERROR`	Invalid input	Check input schema

Self-Hosted Setup

For self-hosted Moira:

Deploy Moira server
Configure MCP endpoint URL
Set up authentication (optional)
Update client configuration with your endpoint

Troubleshooting

Connection Timeout

Check network connectivity
Verify endpoint URL
Ensure SSE is not blocked by firewall

Tools Not Appearing

Restart client after configuration
Verify JSON syntax in config
Check client logs for errors

Authentication Loop

Clear stored tokens
Check OAuth configuration
Verify redirect URIs

Claude Code - Claude Code specific setup
Quick Start - General getting started

MCP Clients Integration

MCP Protocol Overview

Client Configuration

Custom Client

Available Tools

Workflow Management

Session Management

Help & Settings

Authentication

OAuth 2.0 (Default)

API Tokens

Tool Call Examples

List Workflows

Start Workflow

Execute Step

Error Handling

Self-Hosted Setup

Troubleshooting

Connection Timeout

Tools Not Appearing

Authentication Loop

Related