Quick Start
This guide helps you connect Moira to your AI client and run your first workflow.
Prerequisites
- An MCP-compatible AI client (see supported clients below)
- Moira account (sign up at Moira)
Setup
-
Get your MCP endpoint
For Moira Cloud:
https://moira-mcp.com/mcpFor self-hosted, use your server’s MCP endpoint.
-
Configure your AI client
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 documentation-
Authenticate the MCP server
Check the selected client’s connection status using its instructions above. If Moira already works, keep that connection. Otherwise complete the client’s supported authentication path: browser OAuth when offered, or its native API-token configuration. Saving a configuration alone does not establish authentication.
No OAuth support?
If your client cannot open a browser for OAuth, create an API token instead:
- Log in to Moira web UI → Settings → Apps & tokens → API tokens
- Create a token and copy it (starts with
moira_) - Use the selected client’s token example above; header placement differs between clients, and Codex references an environment variable. Keep the token out of Git and logs.
See MCP Clients → API Tokens for details.
-
Verify connection
Ask your AI client to list available Moira workflows:
List available Moira workflowsYou should see a list of workflows you have access to.
-
Run your first flow
Ask your agent, in plain words, to run the first learning example on any small task:
Use Moira to run Example 1: Simple Steps for this task: rename the file notes.txt to todo.txtThe agent starts
moira/example-simple-stepsand goes through its four steps — understand the task, do it, check the result, report — one at a time; Moira hands it each step and checks its answer before the next. Open Workflows in the web app and choose the example to see the same steps as a simple diagram.From here on you do not have to name flows at all. Describe what you need, and your agent picks a ready flow or builds one for the task. The tutorial walks through all three learning examples; Which ready flow to use explains the everyday ones.
Want a guided tour of the catalog?
Say
Start user onboarding flow. The interactive onboarding reads your current authorized public catalog, explains how the flows differ, records one exact workflow such asmoira/test-planning, and starts it only if you choose to; deferring changes nothing.
Available MCP Tools
The core execution lifecycle uses these Moira tools:
| Tool | Description |
|---|---|
workflow (list) | List authorized workflows with pagination |
execution (prepare, execute) | Prepare or execute a standalone or parent-linked start |
execution (step) | Submit a verified step result and get the next directive |
execution | Inspect and resume workflow executions |
help | Get Moira documentation and help |
Moira also exposes workflow management, settings, notes, artifacts, locks, reconciliation, and large-file token operations. See the MCP tools reference for the complete current catalog, exact input schemas, supported actions, and examples.
Example Session
Here’s what a typical workflow session looks like:
Agent: I'll start the full development workflow. [calls execution with action: "prepare", workflowId: "moira/software-development-flow", parentExecutionId: "none"]
Moira: Start attempt ID: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
Agent: [calls execution with action: "execute" and that exact startAttemptId; after a lost reply, repeats this execute call instead of preparing again]
Moira: Process ID: 123e4567-e89b-42d3-a456-426614174000 Step attempt ID: 11111111-1111-4111-8111-111111111111 Your next task: Analyze the requirements document... Success criteria: Requirements are documented...
Agent: [analyzes requirements, produces output] [calls execution with action: "step" with the exact Process ID, current Step attempt ID, and schema-valid evidence]
Moira: Process ID: 123e4567-e89b-42d3-a456-426614174000 Step attempt ID: 22222222-2222-4222-8222-222222222222 Your next task: Create implementation plan... Success criteria: Plan covers all requirements...
[... workflow continues until completion]Next Steps
- Tutorial: your first flows - Three tiny learning flows
- Which ready flow to use - Everyday tasks without building a flow
- Workflows - Understand workflow structure
- Claude Code Integration - Detailed Claude Code setup
- MCP Clients - Other MCP client integrations