> ## 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](/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`](/cli-reference/momentic/commands/mcp) and
[`momentic-mobile mcp`](/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

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](/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
```

## Spec-driven development

Once your repo is on the simplified format, Momentic tests are readable enough
to double as product specs. If you want coding agents to keep tests aligned with
feature work, 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 any UI implementation, sketch the desired user flows as
  Momentic tests. Prefer `act` steps (AI action V3) with a clear `goal` so each
  flow reads as a high-level spec rather than pinning down every click.
- After any UI change, update the relevant Momentic tests so they describe the
  new behavior.
```

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

## Verify

Start a new chat and ask the agent which MCP tools are available. You should see
`momentic_*` tools (e.g. `momentic_get_artifacts`). If they don't appear, fully
restart the editor.

## Usage tips

* **Model**: latest frontier models perform best. `High` reasoning maximizes
  quality; `Medium` is about 20% faster with acceptable quality.
* **Invoke the skill** explicitly (e.g. `/momentic` in Codex).
* **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.