MCP

The Model Context Protocol (MCP) enables AI models to interact with your local Momentic tests via the desktop server. This allows AI assistants in various IDEs to understand, create, and modify your test suites directly.

MCP is currently publicly available for the Momentic local app as of version 2.17.1

Overview

The MCP server provides AI models with access to your Momentic project through a set of specialized tools. These tools allow AI assistants to:

Browse and understand your test structure
Create new tests with AI assistance
Edit existing tests using natural language
Manage test environments and configurations
Access test and module information

Before you start

Local only: The desktop MCP server runs on your machine so remember to run the momentic application before trying to connect to the MCP server.IDE support: Use an editor that supports MCP (e.g., Cursor, Windsurf, Claude Desktop, Codex, VS Code/Copilot).Project configured: Ensure your project has a valid momentic.config.yaml

Step 1: Enable the MCP server

We support three transport options. New features will target the Streamable HTTP and stdio standard, but SSE remains available for legacy IDEs.

Streamable HTTP (Default)
Stdio (CLI's mcp command)
SSE (Legacy)

Streamable HTTP Transport (newer standard): available in any version Momentic >= 2.17.2 Requires the Momentic app to be running.

POST/GET/DELETE /api/mcp/
Header: mcp-session-id: <session-id>
url: http://localhost:58888/api/mcp

Stdio server: Run Momentic through the CLI instead of connecting to the desktop server URL. This is gated behind the momentic mcp command and is useful when you want the MCP server to start on-demand or prefer a command-based setup.

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

SSE Transport: Available in any version Momentic >= 2.17.1 Requires the Momentic app to be running.

GET /api/mcp/sse
POST /api/mcp/sse?sessionId=<session-id>
url: http://localhost:58888/api/mcp/sse

Step 2: Set up your MCP client

Make sure you have started the local app then follow the steps for your IDE below.

Cursor
VS Code (GitHub Copilot)
Windsurf

Example configuration (used in Cursor as of 2025‑09‑19). This is an example and may not work universally across VS Code–branched IDEs.

{
  "mcpServers": {
    "momentic-desktop": {
      "url": "http://localhost:58888/api/mcp"
    }
  }
}

The momentic mcp command requires Momentic 2.42.0 or later.

Stdio server: Run Momentic through the CLI instead of connecting to the desktop server URL. This is gated behind the momentic mcp command and is useful when you want the MCP server to start on-demand or prefer a command-based setup.

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

Setup Steps:

Open Cursor’s command palette (Cmd Shift P)
Navigate to “View: Open MCP Settings” command
Add the momentic-desktop MCP server (configuration above)
Restart the MCP server

VS Code supports MCP servers. Use the command palette flow or add a workspace mcp.json.Setup Steps:

In VS Code, open Command Palette → “MCP: Add Server”
Follow the setup questions it asks you using the correct URL for your supported transport
Open Extensions and confirm you can connect to the MCP server and it is detecting our tools.
Configure the allowed tools as necessary.

NOTE: GitHub Copilot may need your organization to enable a setting allowing MCP servers.

Example configuration (used in Windsurf as of 2025‑10‑14). This is an example and may not work universally across VS Code–branched IDEs.

{
  "mcpServers": {
    "momentic-desktop": {
      "serverUrl": "http://localhost:58888/api/mcp"
    }
  }
}

Setup Steps:

Open Windsurf’s command palette (Cmd Shift P)
Navigate to “Windsurf: MCP Marketplace” command
Click the settings button on the Installed MCPs Header
Type in the config for the momentic MCP server from above
Restart the MCP server

Step 3: Agent Rules

Open your IDE’s or CLI’s agent‑rules settings and add one of the following suggested rules to prevent models from directly editing your test or module YAML files. If user approval is required before making changes:

Never directly edit a Momentic test (`*.test.yaml`) or module YAML file (`*.module.yaml`), only use the edit test MCP tool, and prompt the user before making changes.

If immediate implementation is OK without user approval:

Never directly edit Momentic test (`*.test.yaml`) or module YAMLs (`*.module.yaml`). Only use the Momentic MCP tools to edit Momentic YAMLs. If they are unavailable tell the user you are unable to edit the YAML files.

NOTE: Many IDEs and CLIs let you hide or protect files from agents (e.g., .cursorignore). Enable these safeguards where available.

Step 4: Use tools in your IDE

Verify you have started the Momentic application
Verify the MCP server appears in your IDE (e.g., Copilot Agent mode → Tools)
Try a simple action (e.g., list tests) to confirm connectivity
If tools don’t appear, restart both the IDE and the Momentic desktop server

NOTE: Several IDEs only provide support for MCP in agent mode

Security considerations

Local Only: The MCP server is designed for local development only
No Authentication: Currently no authentication is required for local access
Session Management: Sessions are automatically cleaned up on disconnection
Resource Access: MCP tools have access to your local file system and project data

Example Usage:

Full Chat Stream Example: Creating and Editing a YC Website Test

User Request:

create a new test called demo test for the yc website

Then once you create that test load its full data, use this to then edit the test

click on the companies tab
choose a major name brand company and click on their profile
check that the team size is visible
click on the jobs tab
assert that the blurb about what the company does is no longer visible

AI Response:I’ll help you create a new test for the YC website and then edit it according to your specifications. Let me start by creating the test and then loading its data to edit it.Creates TODO list:

Create a new test called demo test for the YC website [in_progress]
Load the full data of the created test [pending]
Edit the test to implement the specified flow [pending]

momentic_test_create

Parameters:

name: "demo-test"
baseUrl: "https://www.ycombinator.com"
description: "Test for YC website - companies tab navigation and job page verification"

Result: Successfully created test with ID 391f065b-48f3-4548-ab15-079543fa69e0

momentic_test_get

Parameters:

id: "391f065b-48f3-4548-ab15-079543fa69e0"

Result: Retrieved test configuration with empty steps array

momentic_test_edit

Parameters:

id: "391f065b-48f3-4548-ab15-079543fa69e0"
message: |
  Add test steps to:
  1. Navigate to the YC website
  2. Click on the 'Companies' tab
  3. Find and click on a major brand company like DoorDash or Coinbase
  4. Verify that the team size is visible on the company profile
  5. Click on the 'Jobs' tab
  6. Assert that the company description blurb is no longer visible on the jobs page

Result: Test successfully updated with 7 automated steps:

Navigate to https://www.ycombinator.com
Click on “Companies” tab in navigation
Verify companies list is displayed
Click on DoorDash company profile
Assert team size (8600) is visible
Click on “Jobs” tab
Assert detailed company description is not visible on jobs page

Final Result: ✅ Created “demo-test” for YC website ✅ Implemented complete user flow with proper assertions ✅ Test validates team size visibility and content changes between tabs ✅ Ready to execute with 7 comprehensive test stepsThe AI successfully:

Created a new test with appropriate configuration
Loaded and analyzed the test structure
Converted natural language requirements into specific test steps
Chose DoorDash as the major brand company example
Added proper assertions for team size visibility and content validation
Generated executable test steps ready for automation

Best practices

Start Desktop Server: Always start your Momentic app before connecting MCP
Project Context: Ensure you’re in the correct project directory
Prompting: While you will see success with unclear directions of how to edit a test, using step by step descriptions will yield faster test edit times and steps closer to exactly what you are envisioning. We suggest keeping the amount of steps per edit_test tool call under 10.
Session Management: Allow sessions to clean up properly by disconnecting cleanly
Tool Safety: All of our tools other than edit test currently cannot do any harm or changes to your project (file creation or read only). Enabling these to auto run is safe. If you use the momentic_edit_test tool be sure you have tracked your changes to the test file it is editing as it will not ask you for permission for each change.

Available Tools

Environment Tools

momentic_environment_list

List environments defined in the project’s momentic.config.yaml file.Usage: Returns a JSON array of all configured environments with their settings and configurations.Parameters: NoneExample: momentic_environment_list - Returns all available test environments

Module Tools

momentic_module_list
momentic_module_get
momentic_module_recommend

List all modules in your project.Usage: Returns basic metadata for each module (ID, name, description, and paths). Use this to discover available modules.Parameters: NoneExample: momentic_module_list - Returns all project modulesNote: Parameters are not included in this list. Use momentic_module_get to inspect parameter requirements before inserting modules into a test.

Get a single fully loaded module by ID, exact name, or file path.Usage: Retrieves complete module details including parameters (required inputs), default parameters, parameter enums, and the full step list. Required before inserting a module step so you can provide the right inputs.Parameters:

id (optional): Module ID
name (optional): Exact module name
path (optional): File path

Note: Exactly one selector must be provided.Example: momentic_module_get --name "login-flow" - Returns the login flow module

Use AI to recommend modules that match your request and context.Usage: Returns a list of recommended modules with IDs and reasoning.Parameters:

userRequest (required): Natural-language description of what you want to build or edit

Example: momentic_module_recommend --userRequest "Add login with email and OTP, then verify dashboard loads"Note: After selecting a module, use momentic_module_get to inspect its parameters before inserting it into a test.

Session Tools

momentic_session_start
momentic_session_terminate

Start a granular browser session for a specific test.Usage: Creates a session bound to a test and returns session metadata.Parameters:

testId (required): Test ID to target
envName (optional): Environment override (matches CLI --env)
projectConfigPath (optional): Path to momentic.config.yaml
projectNameFilter (optional): Project name filter for workspace configs
headfulBrowser (optional): Launch a headful browser

Example: momentic_session_start --testId "test-uuid"

Terminate a granular browser session by session ID.Usage: Kills the session and returns available session IDs if none match.Parameters:

sessionId (required): Session ID to terminate

Example: momentic_session_terminate --sessionId "session-uuid"

Test Tools

momentic_test_list
momentic_test_get
momentic_test_create
momentic_test_edit

List all tests in your project.Usage: Returns comprehensive test information including metadata, labels, and file paths.Parameters: NoneExample: momentic_test_list - Returns all project tests

Get a single fully loaded test by ID, exact name, or file path.Usage: Retrieves complete test definition with resolved configurations.Parameters:

id (optional): Test ID
name (optional): Exact test name
path (optional): File path

Note: Exactly one selector must be provided.Example: momentic_test_get --path "tests/login.test.yaml" - Returns the login test

Create a new test using AI assistance.Usage: Creates a test file with specified parameters and AI-generated content.Parameters:

name: Test name (required)
baseUrl or environment: Base URL or environment reference (required)
description: Optional test description
browserType: Browser type (Chromium, Chrome for Testing)
viewport: Viewport dimensions

Example:

momentic_test_create --name "user-registration" --baseUrl "https://app.example.com" --description "Test user registration flow"

Edit an existing test using natural language instructions.Usage: AI-powered test modification based on natural language descriptions.Parameters:

id, name, or path: Test selector (exactly one required)
message: Natural language instructions for the desired changes

Example: momentic_test_edit --name "login-test" --message "Add validation for empty password field"

Test Session Interaction Tools (Granular)

momentic_preview_step
momentic_get_browser_state
momentic_get_environment_variables
momentic_run_step
momentic_test_splice_steps

Execute a step without adding it to the test.Usage: Runs a single step in the current session without modifying the test.Parameters:

sessionId (required): Session ID to use
step (required): Step definition to execute

Example: momentic_preview_step --sessionId "session-uuid" --step { ... }

Get the current browser state for a granular session.Usage: Returns a11y tree data plus a screenshot for the session.Parameters:

sessionId (required): Session ID to query

Example: momentic_get_browser_state --sessionId "session-uuid"

Get the current environment variables for a session.Usage: Returns environment variables available to the active session.Parameters:

sessionId (required): Session ID to query

Example: momentic_get_environment_variables --sessionId "session-uuid"

Run one or more steps from the test bound to an active session.Usage: Executes a range of steps from the test by index.Parameters:

sessionId (required): Session ID to use
fromIndex (required): First step index to run
toIndex (optional): Last step index (inclusive)
targetSection (optional): Test section (main, setup, teardown)

Example: momentic_run_step --sessionId "session-uuid" --fromIndex 0 --toIndex 2

Insert, delete, or replace steps in a test within an active session.Usage: Splices steps by index for the test bound to the session.Parameters:

sessionId (required): Session ID to use
startIndex (required): Index to begin splicing
deleteCount (required): Steps to remove (0 insert, 1 replace, N delete)
steps (required): Step definitions to insert
targetSection (optional): Test section (main, setup, teardown)
returnTest (optional): Return the full test after splicing

Example: momentic_test_splice_steps --sessionId "session-uuid" --startIndex 1 --deleteCount 0 --steps [ ... ]

Getting Started

Core concepts

Features

CLI

Mobile CLI

CI/CD

Resources

Overview

Before you start

Step 1: Enable the MCP server

Step 2: Set up your MCP client

Step 3: Agent Rules

Step 4: Use tools in your IDE

Security considerations

Example Usage:

Best practices

Available Tools

Environment Tools

Module Tools

Session Tools

Test Tools

Test Session Interaction Tools (Granular)

Getting Started

Core concepts

Features

CLI

Mobile CLI

CI/CD

Resources

​Overview

​Before you start

​Step 1: Enable the MCP server

​Step 2: Set up your MCP client

​Step 3: Agent Rules

​Step 4: Use tools in your IDE

​Security considerations

​Example Usage:

​Best practices

​Available Tools

​Environment Tools

​Module Tools

​Session Tools

​Test Tools

​Test Session Interaction Tools (Granular)

Overview

Before you start

Step 1: Enable the MCP server

Step 2: Set up your MCP client

Step 3: Agent Rules

Step 4: Use tools in your IDE

Security considerations

Example Usage:

Best practices

Available Tools

Environment Tools

Module Tools

Session Tools

Test Tools

Test Session Interaction Tools (Granular)