MCP - Momentic

Documentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

The explore agent (momentic ai explore) is deprecated. Mo now handles autonomous bug finding. To write tests from a code diff, use the MCP server with the momentic-spec skill.

Momentic’s MCP server is a local process that gives a coding agent a live browser or device and tools to browse, edit, run, and triage tests. The skills teach the agent which tools to call and in what order. Install both.

Requires Momentic CLI 2.54.0 or later.

Prerequisites

Setup instructions

Run install-mcp to detect the coding agents on your machine. It writes the server entry into each one’s config. Use momentic-mobile install-mcp for mobile projects; it registers a separate momentic-mobile server, so web and mobile can live in the same config.

npx momentic install-mcp

See momentic install-mcp for --client, --scope, and noninteractive use.

Momentic’s MCP is a local stdio server. Every client ultimately runs one of these commands:

Web

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

Mobile

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

See momentic mcp and momentic-mobile mcp for every supported flag (headful browser, pixel ratio, daemon mode, etc.).

After the server is registered, 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.

npx momentic install-mcp --client claude-code

Or register the server with the Claude Code CLI:

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:

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 for scoping and auth options. Run /mcp to confirm the server is active.

npx momentic install-mcp --client cursor

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

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

npx momentic install-mcp --client vscode

Or 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:

{
  "servers": {
    "momentic": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "momentic",
        "mcp",
        "--config",
        "/absolute/path/to/momentic.config.yaml"
      ],
      "env": { "MOMENTIC_API_KEY": "your-api-key" }
    }
  }
}

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

npx momentic install-mcp --client codex

Or register the server with the Codex CLI:

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 for env vars and timeouts. Restart Codex, then run /mcp in the TUI to verify.

npx momentic install-mcp --client opencode

Or edit opencode.json in your project root or ~/.config/opencode/:

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

Use the setup wizard to configure Momentic in Devin. You can also give Devin the agent setup prompt.

install-mcp also supports gemini-cli, windsurf, zed, antigravity, and claude-desktop. Any other MCP-compatible client can launch the server with:

Example prompts

Choose a task and copy its prompt into your coding agent. Replace the test filenames and run ID with your own. For longer jobs, invoke a skill by name. The skill tells the agent which tools to call and in what order.

Check the MCP connection

List the available Momentic MCP tools and call one to verify the connection.

Preview a test

Preview the steps in checkout.test.yaml using Momentic MCP.
Show me the screenshots.

Run and repair a test

Run login.test.yaml using Momentic MCP. Inspect the failed step and
screenshots before fixing the test, then rerun it and show me the result.

Inspect a past run

Show me the artifacts for Momentic run <run-id>.

Lint test files

Lint all Momentic test files in this repository and fix the errors.

Look up documentation

Search the Momentic docs for how to wait for network idle.

Write your first test with the agent

The agent writes a .test.yaml, runs it through the MCP server, reads the structured failure with the failed step, screenshot, and trace, then fixes its own test. Verify the server with claude mcp list in Claude Code, or turn it on in Cursor’s MCP settings. Start a new chat. This web example uses an email-only login flow. Replace the URL and test account with your app’s values, and adapt the steps to your login flow.

  1. Write the test
    Ask the agent to write a test with a base URL:

    Use the Momentic MCP server and the `momentic-test` skill to write
`login.test.yaml` in YAML. Set the top-level `url` to
`https://app.example.com/login` and save the file in this repository.
Enter `test@example.com` in the Email field, click Continue, and assert
that the dashboard is visible after login.

  2. Run and repair the test
    Ask the agent to run the test and fix any failures:

   Run `login.test.yaml` through the Momentic MCP server. Read any structured
   failure, including the failed step, screenshot, and trace. Fix the failing
   step in the test file, then run it again.
  1. Commit the test
    Review the resulting file, then commit it:
   git add login.test.yaml
   git commit -m "Add login test"

The momentic-test skill covers the authoring flow, and GitHub Actions runs the test in CI. The test opens the top-level url before it runs the steps:

login.test.yaml

fileType: momentic/test/v2
id: login-flow
url: https://app.example.com/login
steps:
  - type:
      text: test@example.com
      into: Email
  - click: Continue
  - assert: The dashboard is visible

Usage tips

Choose a model that can call tools and follow the installed skills. Reasoning settings affect latency and decisions; compare them on your own tests before changing the team default. Invoke the relevant skill by name when authoring, maintaining, or changing product behavior. Be specific in prompts, and include a step limit for exploratory runs. Let sessions terminate on their own. The agent calls momentic_session_terminate to close the browser; hard-stopping your editor leaks browser processes. Add .momentic-mcp/ to .gitignore. MCP stores screenshots, videos, and traces there. Tell the agent to call momentic_search_docs before it writes step options, CLI flags, or configuration keys from memory. The tool searches these docs and returns the matching sections with their links. momentic_preview_step, momentic_preview_steps, and momentic_run_step wait 30 seconds by default, which you can change with timeoutSeconds. Work that takes longer continues in the background and the tool returns a stepRunnerId. Collect the result with momentic_poll_runner, and pass its own timeoutSeconds (0-30, default 0) to hold the poll open instead of busy-polling. Only one preview or run executes per session at a time. Both servers expose run history: momentic_list_runs, momentic_get_run, momentic_get_test_steps_for_run, and momentic_get_step_result read past runs from the dashboard so an agent can triage a CI failure without leaving the editor. The momentic-mobile server lists Android and iOS runs by default; pass executionType to pick one platform or include web runs.