Version: 2.27

Setup and Integration

This page walks you through connecting the Cycle MCP server to a coding agent. Setup is a one-time configuration per agent: you paste a small JSON block into the agent's MCP config file, and from then on the agent has access to Cycle's tools.

Every agent's config block points at the same binary with the same single argument:

command: the absolute path to cycle-cli.exe — installed by default at C:\Program Files (x86)\CycleLabs\Cycle\cycle-cli.exe (substitute your custom install path if you changed it).
args: ["--mcp"] — this flag switches cycle-cli.exe into a stdio MCP server. You do not need to run it directly; the agent launches it.

Agent Setup Differences

The exact JSON shape differs slightly between agents — the sections below give you a copy-paste block for each one. Additionally, each agent has scoping for project/workspace or user. Project-scoped is used when the test project lives in a shared repository and you want everyone who clones the repo to get the Cycle MCP server automatically. User-scoped is used to make the Cycle MCP server available in every repository you open with the agent, without committing a config file.

After editing any agent's MCP config, restart the agent (or its host IDE) — MCP servers are spawned at startup and config changes require a fresh launch.

Claude Code

For Project-scoped, create a file named .mcp.json at the root of the repository with the following contents:

{
  "mcpServers": {
    "cycle": {
      "command": "C:/Program Files (x86)/CycleLabs/Cycle/cycle-cli.exe",
      "args": ["--mcp"]
    }
  }
}

Commit .mcp.json to source control. Anyone who opens the repo with Claude Code and approves the server on first launch will then have Cycle's tools available.

For User-scoped, open a terminal and run:

claude mcp add cycle "C:/Program Files (x86)/CycleLabs/Cycle/cycle-cli.exe" -- --mcp

This writes the server to your user-level Claude Code config. You can confirm it registered with claude mcp list.

To Verify either way:

Restart Claude Code (or close and re-open the IDE that hosts it).
Start a chat and ask: "List the categories available in the cycle MCP server."
The agent should respond with a JSON list of step categories (Web, File Action, Comparison, etc.). If it does, setup is complete.

Cursor

For Project-scoped, create the file .cursor/mcp.json at the root of your repository:

{
  "mcpServers": {
    "cycle": {
      "command": "C:/Program Files (x86)/CycleLabs/Cycle/cycle-cli.exe",
      "args": ["--mcp"]
    }
  }
}

Commit .cursor/mcp.json to source control. Anyone who opens the repo with Cursor and approves the server on first launch will then have Cycle's tools available.

For User-scoped, use the Settings UI:

Open Cursor.
Go to Cursor Settings → Cursor Settings → MCP.
Click Add new MCP Server.
Set:
- Name: cycle
- Command: C:/Program Files (x86)/CycleLabs/Cycle/cycle-cli.exe
- Args: --mcp
Save.

To Verify:

Restart Cursor.
Open the chat panel and confirm the cycle server appears in the MCP servers list with a green/healthy indicator.
Ask: "What step categories does the cycle MCP server expose?" You should get a JSON list back.

GitHub Copilot in VS Code

VS Code uses a different schema than Claude Code and Cursor:

The top-level key is servers (not mcpServers).
Each server entry includes a type field. Set type to "stdio" for the cycle server.

For Workspace-scoped, create a .vscode/mcp.json file at the root of your workspace:

{
  "servers": {
    "cycle": {
      "type": "stdio",
      "command": "C:/Program Files (x86)/CycleLabs/Cycle/cycle-cli.exe",
      "args": ["--mcp"]
    }
  }
}

For User-scoped:

Open VS Code.
Open the Command Palette (Ctrl+Shift+P) and run MCP: Open User Configuration.
Add the same servers.cycle block shown above.
Save.

To Verify:

Open the Copilot Chat panel and switch it to agent mode (Copilot's tool-using mode).
Ask: "Use the cycle MCP server to list the available step categories."
Copilot should call the cycle://categories resource and return a JSON list.

Adding Agent Rules

Although optional for setup, we recommend creating rules to guide the agent's thinking. The Cycle MCP server exposes tools, but it doesn't tell the agent when to call them. A small rules / instructions file dramatically improves how the agent uses Cycle — for example, reminding it to take a live page snapshot before guessing at element locators.

Each agent has its own rules-file location:

Agent	File	Notes
Claude Code	`CLAUDE.md` (at the repo root)	Claude Code's project-memory file — always loaded when Claude Code is invoked inside the repo.
Cursor	`.cursor/rules/cycle-mcp.mdc`	Cursor's rules format — `.mdc` files with optional metadata.
Copilot in VS Code	`.github/copilot-instructions.md`	Repository-wide instructions visible to Copilot.

A minimal recommended rules file looks like this. The example uses Claude Code's mcp__cycle__<tool> tool-name convention; adapt the file extension and the tool-name prefix to match your agent's MCP namespacing convention (Cursor and Copilot expose MCP tools under different names than Claude Code does).

# Cycle MCP rules

When writing or debugging Cycle `.feature` files, prefer the `cycle` MCP server's tools over guessing.

- Before writing any web locator, call `mcp__cycle__run_step` with `step_id: "WebDriver.snapshotPage"` to see the live page's accessibility tree. Do not guess locators.
- Use `mcp__cycle__search_steps` (with a category) to find unfamiliar step syntax — do not rely on memory.
- Always call `mcp__cycle__validate_feature` before `mcp__cycle__run_test` to catch syntax errors cheaply.
- After a failed `run_test`, always call `mcp__cycle__get_run_errors` with the returned `dbDir` to get structured error details.
- Read `cycle://authoring-guide` once before writing any feature, and `cycle://locator-formats` before any web locator work.

Updating Cycle

When you install a newer version of Cycle, the installer overwrites cycle-cli.exe. Your agent's MCP configuration does not need to change — the install path is stable.

You'll need to restart your coding agent after a Cycle upgrade so it picks up the new binary and any new tools or resources.

Uninstalling

When Cycle is uninstalled, cycle-cli.exe is removed along with everything else. Your agent's MCP config still references the path; if you don't remove that block, the agent will fail to launch the server on the next startup.

To clean up:

Claude Code: delete the cycle entry from .mcp.json (project) or run claude mcp remove cycle (user).
Cursor: remove the cycle entry from .cursor/mcp.json (project) or delete it from Cursor Settings → MCP (user).
Copilot in VS Code: delete the cycle entry from .vscode/mcp.json (workspace) or your user MCP configuration.

Agent Setup Differences​

Claude Code​

Cursor​

GitHub Copilot in VS Code​

Adding Agent Rules​

Updating Cycle​

Uninstalling​