Ghostly MCP Server: AI Testing Tool Reference

The Model Context Protocol (MCP) is an open standard that lets AI coding assistants call external tools as part of their reasoning loop. Ghostly ships a fully-featured MCP server that exposes six tools — covering local test execution, project scanning, component analysis, and API submission — so an IDE agent such as Cursor’s Composer can plan and run end-to-end tests without you ever switching context away from your editor.

How the MCP server is packaged

The MCP server lives inside @ghostly-io/cli and is bundled at install time. Running ghostly install is the recommended way to register it; the CLI writes a ghostly entry directly into ~/.cursor/mcp.json and any other IDE config directories it detects.

ghostly install requires that ghostly keygen has been run at least once on the machine so that a valid API key exists to embed in the MCP configuration.

Manual configuration

If you prefer to add the entry by hand, or if you are configuring a second IDE, add the following block to your mcp.json. Replace the bracketed values with your actual key and API URL.

{
  "mcpServers": {
    "ghostly": {
      "command": "node",
      "args": ["/path/to/node_modules/@ghostly-io/cli/dist/assets/mcp-server/index.js"],
      "env": {
        "GHOST_API_KEY": "<your-api-key>",
        "X_API_KEY": "<your-api-key>",
        "GHOST_API_URL": "http://localhost:4000"
      }
    }
  }
}

On Windows the resolved path will look like %APPDATA%\npm\node_modules\@ghostly-io\cli\dist\assets\mcp-server\index.js. Use the output of ghostly install --dry-run (if available) or check the npm root -g location on your machine.

Tool reference

The MCP server registers the following six tools. All tools communicate over stdio using the MCP standard and return structured JSON.

`ghostly_run_flow`

Executes a Playwright flow directly inside the MCP server process using @ghostly-io/runner — no API call is made. The run will not appear in the dashboard.

Parameter	Type	Required	Description
`baseUrl`	`string` (URL)	Yes	The base URL to run the flow against.
`stepsJson`	`string`	Yes	JSON-serialized array of step objects.
`headless`	`boolean`	No	Run the browser in headless mode.
`captureA11yAfterEachStep`	`boolean`	No	Capture the accessibility tree after each step.
`captureScreenshotAfterEachStep`	`boolean`	No	Capture a screenshot after each step.
`recordVideoOnFailure`	`boolean`	No	Record a video when the run fails.
`artifactsDir`	`string`	No	Directory to write screenshots and videos into.
`defaultTimeoutMs`	`number`	No	Default timeout in milliseconds for each step.

`submit_plan`

Sends an enriched plan to POST /v1/run. Automatically reads the local scanner manifest and attaches codeHints (routes, selectors, forms). Screenshots are captured after each step by default.

Parameter	Type	Required	Description
`project`	`string`	Yes	Ghostly project ID (from `list_ghostly_projects`).
`goal`	`string`	Yes	Natural-language goal description for the run.
`baseUrl`	`string` (URL)	Yes	The base URL to run the flow against.
`stepsJson`	`string`	Yes	JSON-serialized array of step objects.
`assisted`	`boolean`	No	Attach assisted metadata (v1 mode) to the run.
`assistV2`	`boolean`	No	Enable assisted v2 mode with self-healing and victory checks.
`victoryTextIncludes`	`string[]`	No	Pass if the page contains all listed text strings.
`victorySelectorVisible`	`string[]`	No	Pass if all listed CSS selectors are visible.
`victoryUrlIncludes`	`string[]`	No	Pass if the final URL contains all listed substrings.
`victoryMustAll`	`boolean`	No	Require all victory conditions to pass (logical AND). Defaults to OR.
`headless`	`boolean`	No	Run the browser in headless mode.
`captureScreenshotAfterEachStep`	`boolean`	No	Capture a screenshot after each step. Defaults to `true`.
`recordVideoOnFailure`	`boolean`	No	Record a video on failure. Defaults to `true`.
`captureA11yAfterEachStep`	`boolean`	No	Capture the accessibility tree after each step. Defaults to `false`.
`artifactsDir`	`string`	No	Directory to write screenshots and videos into.
`defaultTimeoutMs`	`number`	No	Default step timeout in milliseconds.
`contextId`	`string`	No	Override the context ID (defaults to the git commit from the manifest).
`manifestPath`	`string`	No	Explicit path to `ghost-manifest.json`.
`projectRoot`	`string`	No	Root directory of the project to scan.
`apiUrl`	`string` (URL)	No	Override the Ghostly API URL (defaults to `GHOST_API_URL` env var).
`apiKey`	`string`	No	Override the API key (defaults to `GHOST_API_KEY` env var).

`get_project_map`

Reads ghost-manifest.json and returns the full scanner manifest: routes, components, forms, and selectors.

Parameter	Type	Required	Description
`projectRoot`	`string`	No	Root directory of the project to scan.
`manifestPath`	`string`	No	Explicit path to `ghost-manifest.json`.

`analyze_component`

Filters the scanner manifest to components and forms matching a given name or file path.

Parameter	Type	Required	Description
`componentName`	`string`	No	Component name to filter by (case-insensitive).
`filePath`	`string`	No	File path to filter by (case-insensitive).
`projectRoot`	`string`	No	Root directory of the project to scan.
`manifestPath`	`string`	No	Explicit path to `ghost-manifest.json`.

`list_ghostly_projects`

Calls GET /v1/projects and returns all projects for the configured user. Use the returned id field as the project parameter in submit_plan.

Parameter	Type	Required	Description
`apiUrl`	`string` (URL)	No	Override the Ghostly API URL (defaults to `GHOST_API_URL` env var).
`apiKey`	`string`	No	Override the API key (defaults to `GHOST_API_KEY` env var).

`read_flow_docs`

Finds a named flow in ghost-manifest.json and reads its .ghost.md documentation file from disk.

Parameter	Type	Required	Description
`flowName`	`string`	Yes	The name of the flow to look up (case-insensitive).
`projectRoot`	`string`	No	Root directory of the project to scan.
`manifestPath`	`string`	No	Explicit path to `ghost-manifest.json`.

ghostly_run_flow runs the flow locally inside the MCP server process using the bundled Playwright runner. It does not contact the Ghostly API and the run will not appear in the dashboard. Use submit_plan when you want dashboard visibility, SSE streaming, and run persistence.

Step definitions

Both ghostly_run_flow and submit_plan accept a stepsJson parameter — a JSON-serialized array of step objects. Each step must include an action field matching one of the six supported action types.

Supported step action types

type Step =
  | { action: "goto"; url: string }
  | { action: "click"; selector: string }
  | { action: "fill"; selector: string; value: string }
  | { action: "press"; key: string }
  | { action: "waitForSelector"; selector: string; timeoutMs?: number }
  | { action: "snapshot" }

Example stepsJson value:

[
  { "action": "goto", "url": "http://localhost:3000/login" },
  { "action": "fill", "selector": "[data-testid='email']", "value": "user@example.com" },
  { "action": "fill", "selector": "[data-testid='password']", "value": "secret" },
  { "action": "click", "selector": "[data-testid='submit']" },
  { "action": "waitForSelector", "selector": "[data-testid='dashboard']" },
  { "action": "snapshot" }
]

The snapshot action captures the current accessibility tree state and attaches it to the run record. It has no required fields beyond action.

Victory conditions (submit_plan)

When using submit_plan with assistV2: true, you can declare one or more victory conditions that the engine checks after the final step. All conditions are optional and can be combined.

victoryTextIncludes

Passes if the rendered page contains all of the specified text strings.

victorySelectorVisible

Passes if every listed CSS selector is visible in the DOM after the last step.

victoryUrlIncludes

Passes if the final page URL contains all of the specified substrings.

Set victoryMustAll: true to require all conditions to be satisfied simultaneously (logical AND). The default behaviour requires at least one condition to pass (logical OR).

Authentication

The MCP server reads auth credentials from environment variables injected by the IDE at startup. API keys are sent using the X-Api-Key header; JWT tokens are sent as Authorization: Bearer <token>. Both are handled automatically based on the token format.

GHOST_API_KEY   — API key (preferred)
GHOST_API_TOKEN — alternative JWT token
GHOST_API_URL   — base URL, defaults to http://localhost:4000

The MCP environment block in mcp.json stores the API key in plaintext. Never commit this file to a public repository.

Get Started

CLI Reference

Core Concepts

Integrations

Configuration

Ghostly MCP Server: AI Testing Tool Reference

How the MCP server is packaged

Manual configuration

Tool reference

`ghostly_run_flow`

`submit_plan`

`get_project_map`

`analyze_component`

`list_ghostly_projects`

`read_flow_docs`

Step definitions

Victory conditions (submit_plan)

victoryTextIncludes

victorySelectorVisible

victoryUrlIncludes

Authentication

Build docs developers (and LLMs) love

Get Started

CLI Reference

Core Concepts

Integrations

Configuration

Documentation Index

​How the MCP server is packaged

​Manual configuration

​Tool reference

​ghostly_run_flow

​submit_plan

​get_project_map

​analyze_component

​list_ghostly_projects

​read_flow_docs

​Step definitions

​Victory conditions (submit_plan)

victoryTextIncludes

victorySelectorVisible

victoryUrlIncludes

​Authentication

Build docs developers (and LLMs) love

How the MCP server is packaged

Manual configuration

Tool reference

`ghostly_run_flow`

`submit_plan`

`get_project_map`

`analyze_component`

`list_ghostly_projects`

`read_flow_docs`

Step definitions

Victory conditions (submit_plan)

Authentication