> ## 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>

## 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-result-classification`**: how to analyze and classify failures
* **`momentic-spec`**: how to write affected tests before product changes

<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.

The setup for each editor is below.

### 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
```

Saved 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

Agents don't always pick up installed skills. Some load them on their own;
naming the skill in the prompt is the only way to be sure. The examples below
use Codex's `$<skill>` syntax. In Claude Code and Cursor, replace `$` with `/`.
For other agents, 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-test` to repair stale test steps while preserving the intended
behavior. Use `momentic-result-classification` when you want the agent to
explain or classify a failing run before changing anything:

```text theme={null}
$momentic-test run the affected tests and fix stale test steps
$momentic-result-classification classify 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.). Tune the wording to your
team's workflow:

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

- Before starting implementation, create Momentic tests for new user-visible
  functionality or update the existing tests for behavior that will change.
  Treat these tests as the product specification; do not make them fit the code.
- Mark specifications `disabled: true` when they are not expected to pass yet,
  and record the exact tests expected to be affected.
- For new tests, prefer `act` steps (AI action V3) with a clear `goal` when a
  high-level flow reads better than individual clicks. Reuse existing modules
  for established subflows.
- Do not run Momentic after every edit or commit. Use it as end-to-end
  validation at durable, usable UI checkpoints: after full implementation for a
  small change, or after an independently testable UI slice for a large change.
- The coding agent owns required test data and state. Prefer existing setup
  facilities, or add safe test-environment-only seeding endpoints, fixtures,
  accounts, and controls when needed.
- At each checkpoint, establish the required state, enable the specifications
  expected to pass, and run the smallest affected test set.
```

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)