> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Run Momentic's MCP server so coding agents can author, run, and triage tests directly from your editor.

Momentic's MCP server exposes tools that let agents browse, edit, create, and
run tests with a live browser directly from your editor.

<Warning>Requires Momentic CLI 2.54.0 or later.</Warning>

## Common workflows

* **Implement from executable specs.** Use `momentic-spec` before changing
  user-visible behavior so the affected Momentic tests capture the intended
  product behavior and validate the finished implementation.
* **Author and extend coverage.** Use `momentic-test` to create tests, steps,
  and modules against a live browser. Use `momentic-mobile-test` for Android and
  iOS.
* **Understand a branch failure.** Use `momentic-maintain` to find runs for the
  branch, inspect the saved classifications and run evidence, and identify the
  earliest point where behavior diverged.
* **Investigate failures on main.** DevX and on-call engineers can group recent
  failures by status or classification, inspect representative runs, and
  distinguish application regressions from test, environment, and Momentic
  issues.
* **Deflake tests and reduce latency.** Find quarantined, recovered, and
  retry-heavy runs, then repair unstable tests and reduce time spent in failure
  recovery. Branch, classification, and minimum-attempt filters help prioritize
  repeated failure patterns.

## Prerequisites

* [Momentic CLI](/docs/quickstart/web) installed locally (MCP runs on your machine)
* A project with a valid `momentic.config.yaml`
* A `MOMENTIC_API_KEY` available to the MCP process (most editors do **not**
  inherit your shell environment)

## Setup instructions

### General

Momentic's MCP is a **local stdio server**. Every editor ultimately runs:

```
npx momentic mcp --config /absolute/path/to/momentic.config.yaml
```

For mobile testing, substitute `momentic-mobile mcp`. See
[`momentic mcp`](/docs/cli-reference/momentic/commands/mcp) and
[`momentic-mobile mcp`](/docs/cli-reference/momentic-mobile/commands/mcp) for every
supported flag (headful browser, pixel ratio, daemon mode, etc.).

Along with the server, install the **Momentic skills** for your editor. Skills
give agents explicit operating guidance so they don't make malformed tool calls:

* **`momentic-test`**: how to build reliable tests, steps, and modules
* **`momentic-spec`**: how to write affected tests before product changes
* **`momentic-maintain`**: how to investigate branch and main failures, audit
  classifications, deflake quarantined or recovered tests, reduce retries, and
  repair durable test issues

<div id="verify" />

After registering the server with one of the clients below, restart the client
and start a new chat. Ask the agent which MCP tools are available. You should
see `momentic_*` tools such as `momentic_get_artifacts`. If they do not appear,
fully restart the client.

### Claude Code

Register the server:

```bash theme={null}
claude mcp add --transport stdio momentic -- npx momentic mcp --config /absolute/path/to/momentic.config.yaml
```

Verify with `claude mcp list`. On native Windows, wrap with `cmd /c`:

```bash theme={null}
claude mcp add --transport stdio momentic -- cmd /c npx momentic mcp --config C:\path\to\momentic.config.yaml
```

Pass `MOMENTIC_API_KEY` via the CLI's `--env` flag or by running the command
from a shell that already has it exported. See
[Claude Code MCP docs](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server)
for scoping and auth options.

Restart Claude Code and run `/mcp` to confirm the server is active.

### Codex

Register the server:

```bash theme={null}
codex mcp add momentic -- npx momentic mcp --config /absolute/path/to/momentic.config.yaml
```

The command saves the entry to `~/.codex/config.toml`. For project-scoped
configs, edit `.codex/config.toml` in a trusted project. See
[Codex MCP docs](https://developers.openai.com/codex/mcp/) for env vars and
timeouts.

Restart Codex, then run `/mcp` in the TUI to verify.

### Cursor

Open the command palette, select **View: Open MCP Settings**, click **Add a new
Custom MCP server**, then paste and restart Cursor:

```json theme={null}
{
  "mcpServers": {
    "momentic": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "momentic",
        "mcp",
        "--config",
        "/absolute/path/to/momentic.config.yaml"
      ],
      "env": { "MOMENTIC_API_KEY": "your-api-key" }
    }
  }
}
```

### Devin

Follow the dedicated [Devin integration page](/docs/integrations/devin). Devin
requires additional machine-configuration steps so it can install browsers, set
`ANDROID_HOME` / `JAVA_HOME`, and pre-install skills before MCP starts.

### OpenCode

Edit `opencode.json` in your project root or `~/.config/opencode/`:

```json theme={null}
{
  "mcp": {
    "momentic": {
      "type": "local",
      "command": [
        "npx",
        "momentic",
        "mcp",
        "--config",
        "/absolute/path/to/momentic.config.yaml"
      ],
      "environment": { "MOMENTIC_API_KEY": "your-api-key" },
      "enabled": true
    }
  }
}
```

### VS Code (Copilot)

Open the command palette, select **MCP: Add Server**, pick **Command (stdio)**,
then paste:

```
npx momentic mcp --config /absolute/path/to/momentic.config.yaml
```

Name the server `momentic` when prompted. Then add `MOMENTIC_API_KEY` to the
generated entry in `mcp.json`:

```json theme={null}
"momentic": {
  "env": { "MOMENTIC_API_KEY": "your-api-key" }
}
```

Your org may need to allow MCP. Copilot only exposes MCP in agent mode.

### Other clients

Any MCP-compatible client can launch the server with:

* Command: `npx`
* Arguments: `momentic mcp --config /absolute/path/to/momentic.config.yaml`
* Env: `MOMENTIC_API_KEY=your-api-key`

## Install skills

After registering the MCP server with your editor, install the Momentic skill
files from your project root:

```bash theme={null}
npx skills add momentic-ai/skills
```

## Invoke the skill

Some agents load installed skills on their own, but many skip them unless you
name the skill in the prompt. Invoke skills with a slash prefix, as the examples
below show. For agents without slash commands, ask for the skill by name.

### Authorship

Use `momentic-test` to create or extend Momentic tests:

```text theme={null}
/momentic-test write a test for the checkout flow
```

Use `momentic-mobile-test` for Android and iOS. Naming the skill keeps the agent
on Momentic's test format and MCP workflow instead of hand-rolling browser
automation.

### Maintenance

Use `momentic-maintain` to understand failures on a branch or main, review and
challenge saved classifications, deflake quarantined or recovered tests, reduce
retries, and repair stale test steps while preserving the intended behavior:

```text theme={null}
/momentic-maintain investigate and repair run <run-id>
```

### Spec-driven development

Once your repo is on the simplified format, Momentic tests are readable enough
to double as product specs. Invoke `momentic-spec` when implementing a feature
so the agent creates or updates the smallest set of affected Momentic tests
before changing product code:

```text theme={null}
/momentic-spec add a confirmation message after a file is attached
```

To make this the default behavior for your repository, also add a spec-driven
section to your `AGENTS.md` (or `.cursor/rules`, etc.):

```md theme={null}
## Momentic spec-driven development

Use the `momentic-spec` skill before implementing user-visible product changes.
It captures the intended behavior in the smallest affected set of Momentic
tests, then validates the implementation at durable UI checkpoints. Follow the
skill's workflow for test data, disabled specifications, and verification.
```

See [Agentic testing](/docs/core-concepts/agentic-testing) for more on `act` and AI
action V3.

## Usage tips

* **Model**: use the newest model your editor offers. `High` reasoning gives the
  best results; `Medium` is about 20% faster with some quality loss.
* **Invoke the relevant skill** explicitly when authoring, maintaining, or
  changing product behavior.
* **Be specific** in prompts. For exploratory runs, include a step limit.
* **Let sessions terminate**: the agent calls `momentic_session_terminate` to
  close the browser. Hard-stopping your editor leaks browser processes.
* **Gitignore** `.momentic-mcp/`. MCP stores screenshots, videos, and traces
  there.
* **Long-running steps**: `momentic_run_step` returns within 30 seconds. If the
  step range hasn't finished, it returns a `stepRunnerId` that you can poll with
  `momentic_poll_runner`. Pass an optional `timeoutSeconds` (0-30, default 0) to
  hold the poll open briefly instead of busy-polling.

## Related

* [What is AI-native testing?](/docs/get-started/ai-native-testing#author-with-product-context)