MCP Clients Integration

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

MCP Protocol Overview

Moira exposes tools via MCP over HTTP/SSE:

Endpoint: https://moiraqq.com/mcp
Transport: HTTP with SSE for streaming
Authentication: OAuth 2.0

Client Configuration

Claude Web Setup (claude.ai)

Requires Pro, Max, Team, or Enterprise plan.

Go to Settings → Connectors
Click “Add custom connector”
Enter Server URL: https://moiraqq.com/mcp
Click “Connect”
Complete OAuth authentication in browser

Tools appear in chat after authentication.

ChatGPT Setup (chat.openai.com)

Requires Plus or Pro plan.

Go to Profile → Settings
Navigate to “Connectors” or “Integrations”
Click “Add connector”
Enter Name: MCP Moira, URL: https://moiraqq.com/mcp
Complete OAuth authentication

Free tier does not support MCP connectors.

Desktop & CLI Clients

Claude Code Setup

Recommended: CLI command

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

Then authenticate:

/mcp
# → Select "moira"
# → Click "Authenticate"
# → Browser opens for OAuth

Alternative: Manual config

Edit ~/.config/claude/mcp.json with URL: https://moiraqq.com/mcp

Claude Desktop Setup

Open Settings (⌘+,)
Go to “Connectors” tab
Click “Add custom connector”
Enter Server URL: https://moiraqq.com/mcp
Click “Connect”
Browser opens → OAuth → Done

No file editing required.

Gemini CLI Setup (Experimental)

Edit ~/.gemini/settings.json with URL: https://moiraqq.com/mcp

After saving, run gemini auth for OAuth.

IDE Integrations

Cursor Setup

One-click install available on landing page, or manual setup:

Open Cursor Settings
Navigate to MCP Servers section
Add new server with Name: moira, URL: https://moiraqq.com/mcp
Click “Authenticate” → Browser opens for OAuth

Manual config (~/.cursor/mcp.json) with URL: https://moiraqq.com/mcp

VS Code Setup

Requires MCP extension.

Install MCP extension: ext install mcp-connector
Add to settings.json with URL: https://moiraqq.com/mcp

Or use Command Palette → “MCP: Add Server”.

Continue Setup

Continue is an open-source AI assistant for VS Code.

Install Continue extension
Open config: Ctrl+Shift+P → “Continue: Open config”
Add to config.yaml with URL: https://moiraqq.com/mcp

Restart VS Code and authenticate when prompted.

Zed Setup

Edit ~/.config/zed/settings.json with URL: https://moiraqq.com/mcp

Restart Zed and authenticate.

Perplexity Setup (Mac App)

Requires PerplexityXPC helper.

Settings → Connectors → Install Helper
Click “Add Connector”
Enter Server Name: moira, Command: npx, Args: -y mcp-remote https://moiraqq.com/mcp
Complete OAuth authentication

Paid plan recommended.

Custom Client

For custom MCP client implementations, use the MCP SDK with URL: https://moiraqq.com/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 Flow

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

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