MCP Clients Integration

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

MCP Protocol Overview

Moira exposes tools through MCP Streamable HTTP:

Endpoint: https://moira-mcp.com/mcp
Transport: Streamable HTTP; successful responses may use SSE streaming
Authentication: OAuth 2.1 or API Token

Client Configuration

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

Recommended: Config file

~/.copilot/mcp-config.json

{
  "mcpServers": {
    "moira": {
      "type": "http",
      "url": "https://moira-mcp.com/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-mcp.com/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

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

~/.cursor/mcp.json

{
  "mcpServers": {
    "moira": {
      "url": "https://moira-mcp.com/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-mcp.com/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

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

settings.json

{
  "mcpServers": {
    "moira": {
      "url": "https://moira-mcp.com/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-mcp.com/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-mcp.com/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-mcp.com/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

mcpServers:
  - name: 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.yaml

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

Fast code editor with AI features

~/.config/zed/settings.json

{
  "context_servers": {
    "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/zed/settings.json

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

Google AI terminal assistant

~/.gemini/settings.json

{
  "mcpServers": {
    "moira": {
      "httpUrl": "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

~/.gemini/settings.json

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

Custom Client

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

Available Tools

The core lifecycle is list → start prepare → start execute → repeated step calls, with session for inspecting or resuming executions and help for runtime documentation. The MCP tools reference is the source for the complete current catalog, exact input schemas, actions, and examples.

Authentication

Moira supports two authentication methods:

OAuth 2.1 (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

OAuth token refresh is handled automatically and preserves the catalog state accepted by the previous access token. Catalog refresh after a server contract change is a separate MCP initialization step described below. If the credential expires, re-authentication may be required.

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

Replace YOUR_MCP_ENDPOINT with your Moira MCP endpoint: https://moira-mcp.com/mcp. API tokens skip the OAuth flow entirely — use them when your client cannot open a browser for authentication.

Static Catalog Refresh

Tool descriptions and schemas are a static catalog shipped with the Moira server. A client accepts that catalog during the MCP initialize handshake. This applies to both OAuth access tokens and API tokens.

When the catalog changes, an ordinary request made with a credential that has not initialized the current catalog returns HTTP 426 with upgrade_required. Reconnect or reinitialize the MCP server with the same credential. A successful initialize refreshes the catalog for that credential; it does not require a new API token. OAuth access tokens may rotate independently during automatic refresh without losing their current, stale, or uninitialized catalog state.

Authentication and account checks run before catalog refresh. A revoked or expired credential, or an account that cannot access MCP, still receives its normal authentication or access error.

Tool Call Examples

List Workflows

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

Prepare Workflow Start

{
  "method": "tools/call",
  "params": {
    "name": "start",
    "arguments": {
      "action": "prepare",
      "workflowId": "moira/software-development-flow",
      "parentExecutionId": "none"
    }
  }
}

Preparation returns a startAttemptId without creating an execution. Execute it in a second call:

{
  "method": "tools/call",
  "params": {
    "name": "start",
    "arguments": {
      "action": "execute",
      "startAttemptId": "start-attempt-current"
    }
  }
}

Execute Step

{
  "method": "tools/call",
  "params": {
    "name": "step",
    "arguments": {
      "processId": "abc-123",
      "attemptId": "attempt-current",
      "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
`upgrade_required`	MCP catalog must be refreshed	Reconnect using the same credential
`VALIDATION_ERROR`	Invalid input	Check input schema
`ATTEMPT_PROCESSING`	Duplicate still executing	Retry the same attempt and input
`ATTEMPT_STALE`	Presentation is no longer current	Read `current_step` and retry once
`ATTEMPT_CONFLICT`	Attempt is bound to other input	Read `current_step`; discard old input
`ATTEMPT_INVALID_OR_EXPIRED` (step)	Attempt is unavailable	Read `current_step`; discard attempt
`ATTEMPT_OUTCOME_UNKNOWN`	Effect may have occurred	Inspect the returned Process ID

Self-Hosted Setup

For self-hosted Moira:

Deploy Moira server
Configure MCP endpoint URL
Set up authentication and account access
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

Reconnect the Moira MCP server so the client runs initialize again
Keep the existing OAuth or API-token credential unless it is invalid or expired
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

Authentication

OAuth 2.1 (Default)

API Tokens

Static Catalog Refresh

Tool Call Examples

List Workflows

Prepare Workflow Start

Execute Step

Error Handling

Self-Hosted Setup

Troubleshooting

Connection Timeout

Tools Not Appearing

Authentication Loop

Related