Skip to content

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

Run the command in your project. Its default scope is local to you in that project; add --scope user for all projects. The manual .mcp.json alternative below is project scope; review trust before enabling it. Merge entries into an existing file rather than replacing other servers.

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

When authorization is needed, follow the browser prompt or run the login command. For a remote terminal, claude mcp login moira --no-browser prints a link. Do not repeat login for an already working connection.

Terminal
claude mcp login moira
Manual configuration
.mcp.json
{
  "mcpServers": {
    "moira": {
      "type": "http",
      "url": "https://moira-mcp.com/mcp"
    }
  }
}
Alternative: API token

Use a static API token when you choose token authentication instead of browser OAuth. Keep the token private.

Sign in to Moira → Settings → API Tokens and create a token. Replace moira_YOUR_TOKEN below with that token. Merge this alternative into the client's existing configuration instead of adding a second Moira entry.

.mcp.json
{
  "mcpServers": {
    "moira": {
      "type": "http",
      "url": "https://moira-mcp.com/mcp",
      "headers": {
        "Authorization": "Bearer moira_YOUR_TOKEN"
      }
    }
  }
}

Run claude mcp list or open /mcp in Claude Code and check Moira's connection and tools. Then ask the agent to call Moira's read-only list tool and show the available workflows. A saved configuration alone does not prove a working connection.

Official client documentation

Custom Client

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

Available Tools

Use workflow with action: "list", then execution with prepare, execute and repeated step actions. The same execution group handles 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)

  1. Client connects to the MCP endpoint.
  2. Server requests authentication.
  3. Client opens the OAuth flow in a browser.
  4. User authenticates with Moira.
  5. Client receives an access token.
  6. Subsequent requests include that 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:

  1. Log in to Moira web UI.
  2. Open Settings → Apps & tokens → API tokens.
  3. Choose Create Token, then enter its name and expiration.
  4. Copy the token, shown once and starting with moira_.
  5. Configure the client with Bearer authorization; keep the token out of committed files and logs.

Use the selected client’s token example above. JSON, YAML and TOML clients store authorization differently; do not copy another client’s format. For a custom SDK client, configure Authorization: Bearer moira_... on its HTTP transport to https://moira-mcp.com/mcp.

API tokens skip the OAuth flow entirely. Use the configured endpoint https://moira-mcp.com/mcp and preserve other server entries when merging a token alternative. An already working connection needs no new token or login.

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.

Clients may first probe server/discover. An authenticated discovery request reaches the SDK before catalog acceptance. Moira’s legacy SDK returns an unsupported-method or unsupported-version response so compatible clients can fall back to initialize; discovery itself does not accept the catalog or enable tool calls. This does not advertise support for the 2026 stateless protocol.

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": "workflow",
"arguments": { "action": "list" }
}
}

Prepare Workflow Start

{
"method": "tools/call",
"params": {
"name": "execution",
"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": "execution",
"arguments": {
"action": "execute",
"startAttemptId": "start-attempt-current"
}
}
}

Execute Step

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

Error Handling

Common error responses:

ErrorCauseSolution
UNAUTHORIZEDInvalid/expired tokenRe-authenticate
NOT_FOUNDInvalid workflow/process IDVerify IDs
FORBIDDENNo access to resourceCheck permissions
upgrade_requiredMCP catalog must be refreshedReconnect using the same credential
VALIDATION_ERRORInvalid inputCheck input schema
ATTEMPT_PROCESSINGDuplicate still executingRetry the same attempt and input
ATTEMPT_STALEPresentation is no longer currentRead current_step; reconcile intent before submission
ATTEMPT_CONFLICTAttempt is bound to other inputRead current_step; discard old input
ATTEMPT_INVALID_OR_EXPIRED (step)Attempt is unavailableRead current_step; discard attempt
ATTEMPT_OUTCOME_UNKNOWNEffect may have occurredInspect the returned Process ID

Self-Hosted Setup

For full recovery distinctions, see Troubleshooting. A fresh presentation never authorizes carrying an old answer into another step; an unknown outcome is collected, not automatically replayed.

For self-hosted Moira:

  1. Deploy Moira server
  2. Configure MCP endpoint URL
  3. Set up authentication and account access
  4. 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
  • Check the selected client’s configuration format and diagnostics in its official guide above
  • Check client logs for errors

Authentication Loop

  • Check the selected server URL, account and client status before changing credentials
  • Distinguish authentication refusal from HTTP 426: the latter requires initialization with the same credential
  • Inspect client diagnostics and the official OAuth instructions, including redirect requirements
  • Reauthenticate only when the existing credential is invalid or expired and refresh cannot recover it; do not clear unrelated connections