Version: 2.29

Setup

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, then sign in to Cycle so the agent can use the server. From then on the agent has access to Cycle's tools and resources.

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.

Supported Coding Agents

Presently, Claude Code is the only coding agent officially supported and tested with Cycle MCP. Other coding agents like Cursor and GitHub Copilot in VS Code will work with Cycle MCP as well, but they have not been thoroughly tested.

Agent setup differences

The exact JSON shape differs slightly between agents. The sections below give you a copy-paste block for each one. Each agent also supports project (or workspace) scope and user scope.

Project-scoped: Use 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: Use when you want 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 reopen 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, and so on). 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 > 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.

Signing in to Cycle

The Cycle MCP Server requires Cycle authentication. The only thing that works while you are logged out is the authenticate tool itself. If the agent calls a Cycle capability before you have signed in, it gets back an "authentication required" message instead of a result. This is why the verify checks listed above only succeed once you are signed in. If your first verification returns an auth error, sign in and retry.

To sign in, ask the agent:

Authenticate with Cycle.

The agent calls the authenticate tool, which opens a browser login window. Once you complete the login, access is restored.

A few notes:

The agent uses the same credentials as cycle-cli and the Cycle Desktop IDE. If you are already signed in to Cycle on your machine, the login may complete with little or no interaction.
Tokens can expire. If a session that was working starts failing with authentication errors mid-stream, ask the agent to authenticate again, or sign in through the desktop client to refresh the token.

Setting server flags

The Cycle MCP Server accepts a handful of command-line flags, passed after --mcp in the args array of your agent's MCP configuration. Most users never need to set anything beyond --mcp itself.

Flag	Default	Description
`--plugin-dir`	`plugins/` next to `cycle-cli.exe`	Directory the server scans for installed SDK plugins (WebDriver, File-System, and so on). Override only if your install layout is non-standard.
`--subagents-dir`	`subagents/` next to `cycle-cli.exe`	Directory the server scans for custom subagent definitions. Drop your own `.md` definitions here to extend or override the built-in Agents.
`--debug`	`false`	Forwards plugin stdout/stderr to the server's stderr. Use this only when troubleshooting. See Troubleshooting.
`--log-level` / `-l`	`ERROR`	Log level for the MCP server itself. One of `ERROR`, `INFO`, `DEBUG`. Increase when you want server-side logging without enabling full plugin pass-through via `--debug`.

Example with debug logging enabled:

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

Setting agent rules

Rules set guardrails for coding agents in order to yield better results. If you are working on a standard Cycle project, set up the instruction files documented on the Rules page. These files will steer the agent toward Cycle tools, quieter permissions, and safer write paths.

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 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 do not 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​

Signing in to Cycle​

Setting server flags​

Setting agent rules​

Updating Cycle​

Uninstalling​