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.
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.
claude mcp login moiraManual configuration
{
"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.
{
"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 documentationRun the command to add the HTTP server. User configuration is ~/.copilot/mcp-config.json. Portable project files are .mcp.json or .github/mcp.json; they use mcpServers, not VS Code's servers format. The manual example enables all server tools with tools: ["*"]; narrow that list if required. Organization policy may restrict servers or tools.
copilot mcp add --transport http moira 'https://moira-mcp.com/mcp'In a Copilot CLI session, run the authentication command when needed and complete browser authorization.
/mcp auth moiraManual configuration
{
"mcpServers": {
"moira": {
"type": "http",
"url": "https://moira-mcp.com/mcp",
"tools": [
"*"
]
}
}
}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.
{
"mcpServers": {
"moira": {
"type": "http",
"url": "https://moira-mcp.com/mcp",
"tools": [
"*"
],
"headers": {
"Authorization": "Bearer moira_YOUR_TOKEN"
}
}
}
}Use /mcp show moira to inspect status and tools, or copilot mcp list from the terminal. 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 documentationUse the install button and review Cursor's prompt, or merge the manual entry into ~/.cursor/mcp.json for your user or .cursor/mcp.json for this project. Restart Cursor after manual configuration. Local editor setup does not automatically configure Cloud Agents.
Add to CursorOpen Customize → MCPs and complete the HTTP server's authentication prompt when needed. The token configuration below is an alternative to browser OAuth.
Manual configuration
{
"mcpServers": {
"moira": {
"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.
{
"mcpServers": {
"moira": {
"url": "https://moira-mcp.com/mcp",
"headers": {
"Authorization": "Bearer moira_YOUR_TOKEN"
}
}
}
}Check Moira in Customize → MCPs and the chat's tool list. If it is missing, inspect Output → MCP Logs. 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 documentationOpen Customize → Connectors → + Add → Add custom connector. Enter Moira and the Server URL below, then Continue, review authentication and Add. This is an account-hosted remote connector shared with Claude Web. Its HTTPS endpoint must be reachable from Claude's cloud. Organization owners may need to add it before members connect; Free supports one custom connector.
https://moira-mcp.com/mcpChoose sign-in and complete browser OAuth when requested. An organization member may first need to connect the connector provided by an owner.
In a conversation, open + → Connectors and enable Moira. 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 documentationUse the install button and review the prompt, or merge the manual servers entry into .vscode/mcp.json. For user scope, use VS Code's user MCP configuration command. These examples configure VS Code's native integration, not a separate terminal agent's configuration.
Add to VS CodeReview the workspace/server trust prompt and complete browser sign-in when requested. The token configuration below is a separate authentication alternative.
Manual configuration
{
"servers": {
"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.
{
"servers": {
"moira": {
"type": "http",
"url": "https://moira-mcp.com/mcp",
"headers": {
"Authorization": "Bearer moira_YOUR_TOKEN"
}
}
}
}Run MCP: List Servers, select Moira, then Start Server or Show Output. Check tool discovery and that the selected agent harness enables this server. 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 documentationOn claude.ai, open Customize → Connectors → + Add → Add custom connector. Enter Moira and the Server URL below, then Continue, review authentication and Add. The HTTPS endpoint must be reachable from Claude's cloud. Free supports one custom connector; organization policies and owner setup may also apply.
https://moira-mcp.com/mcpChoose sign-in and complete browser OAuth when requested. Organization members connect the connector an owner has made available.
In a conversation, open + → Connectors and enable Moira. 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 documentationOpen https://chatgpt.com/plugins. Use plus → Add custom MCP server, enter a name and the Server URL below, select authentication, review the warning and Create as a plugin. Install the resulting plugin separately. The HTTPS endpoint must be reachable from ChatGPT's cloud; workspace permissions and security policies may restrict custom servers.
https://moira-mcp.com/mcpSelect OAuth for authenticated Moira and complete authorization when requested.
Select the installed Moira plugin with @ in a conversation and explicitly request its tool. 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 documentationOpen Plugins, or Customize → Connectors during the interface rollout. Choose Add custom → Connector → Add MCP connector → Remote, enter the HTTPS Server URL below, choose Streamable HTTP and Add. Remote connectors are available on supported Pro, Max and Enterprise plans; enterprise permissions may also apply. This remote path needs no Mac helper.
https://moira-mcp.com/mcpChoose OAuth, then open the resulting connector card to authenticate and enable it. The endpoint must be reachable from Perplexity's cloud.
Check that the connector is enabled and available to the current conversation. 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 documentationMerge this fragment into your active Continue YAML configuration, commonly ~/.continue/config.yaml. Keep existing configuration and server entries. A standalone .continue/mcpServers/moira.yaml block additionally needs name, version and schema metadata; this is an active-config fragment, not a complete standalone block.
mcpServers:
- name: moira
type: streamable-http
url: "https://moira-mcp.com/mcp"
requestOptions:
headers:
Authorization: "Bearer moira_YOUR_TOKEN"Use the documented token path: sign in to Moira → Settings → API Tokens, create a token and replace moira_YOUR_TOKEN in the configuration. Authorization belongs under requestOptions.headers. Do not assume that an arbitrary remote server supports browser OAuth in Continue.
Switch to Agent mode and confirm that the agent can use the configured Moira 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 documentationOpen Settings → AI → MCP Servers → Add Server → Add Remote Server and enter the configured endpoint, or merge the context_servers entry below into ~/.config/zed/settings.json. Preserve other settings and servers.
{
"context_servers": {
"moira": {
"url": "https://moira-mcp.com/mcp"
}
}
}With no Authorization header, follow Zed's MCP OAuth prompt when needed. A static Authorization header is the token alternative below.
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.
{
"context_servers": {
"moira": {
"url": "https://moira-mcp.com/mcp",
"headers": {
"Authorization": "Bearer moira_YOUR_TOKEN"
}
}
}
}Look for the green dot and Server is active tooltip, then use Zed Agent. Terminal agents use their own native CLI configuration; another agent harness may have separate server forwarding. 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 documentationRun the command in your project; add --scope user for all projects. The manual alternative can be merged into .gemini/settings.json or ~/.gemini/settings.json. Use httpUrl for Streamable HTTP: Gemini's url field selects legacy SSE.
gemini mcp add --transport http moira 'https://moira-mcp.com/mcp'In a Gemini CLI session, run the authentication command when needed and complete browser OAuth. Use the token alternative when a browser callback is unsuitable.
/mcp auth moiraManual configuration
{
"mcpServers": {
"moira": {
"httpUrl": "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.
{
"mcpServers": {
"moira": {
"httpUrl": "https://moira-mcp.com/mcp",
"headers": {
"Authorization": "Bearer moira_YOUR_TOKEN"
}
}
}
}Run gemini mcp list from the terminal or /mcp list in the session to inspect connection status and errors. 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 documentationRun the command to register the HTTP server, or merge the TOML alternative into ~/.codex/config.toml. A trusted project's .codex/config.toml provides project scope. Configuration is shared by local Codex CLI, desktop and IDE surfaces; do not assume every remote/cloud executor inherits it.
codex mcp add moira --url 'https://moira-mcp.com/mcp'Follow an authorization prompt when offered. If the server still needs authentication, run codex mcp login moira and complete browser sign-in. An already authorized connection needs no repeat login.
codex mcp login moiraManual configuration
[mcp_servers.moira]
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.
Create a token in Moira → Settings → API Tokens. Set MOIRA_API_TOKEN in the environment of the process launching Codex. The TOML field below names that environment variable; it does not contain the token.
[mcp_servers.moira]
url = "https://moira-mcp.com/mcp"
bearer_token_env_var = "MOIRA_API_TOKEN"Run codex mcp list and open /mcp in the active Codex session to check Moira's state and available 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 documentationMerge the direct configuration below into ~/.kimi-code/mcp.json, or .kimi-code/mcp.json for this project, and reload or start a new session. The direct configuration uses this selected server. Project configuration requires workspace trust; an unattended run cannot answer that prompt for you.
{
"mcpServers": {
"moira": {
"url": "https://moira-mcp.com/mcp"
}
}
}In Kimi Code, run /mcp-config login moira when authorization is needed and complete sign-in. The token configuration is an alternative.
/mcp-config login moiraOptional: hosted Moira plugin
This plugin connects to the fixed hosted endpoint https://moira-mcp.com/mcp, not to your selected self-host server. Use the direct configuration above for your own server. Install the repository tree below, then /reload or start a new session.
/plugins install https://github.com/moira-mcp/moira/tree/master
/reloadAlternative: 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.
{
"mcpServers": {
"moira": {
"url": "https://moira-mcp.com/mcp",
"headers": {
"Authorization": "Bearer moira_YOUR_TOKEN"
}
}
}
}Use /mcp to inspect the actual server state. If using the optional hosted plugin, /plugins info moira shows its installation details. 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 documentationCustom 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)
- Client connects to the MCP endpoint.
- Server requests authentication.
- Client opens the OAuth flow in a browser.
- User authenticates with Moira.
- Client receives an access token.
- 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:
- Log in to Moira web UI.
- Open Settings → Apps & tokens → API tokens.
- Choose Create Token, then enter its name and expiration.
- Copy the token, shown once and starting with
moira_. - 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:
| 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; reconcile intent before submission |
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 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:
- 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
initializeagain - 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
Related
- Claude Code - Claude Code specific setup
- Quick Start - General getting started