Troubleshooting

This page lists the issues most users hit when wiring up the Cycle MCP server, and how to recover from each.

Common issues

Issue	Symptoms and cause	What to do
Agent cannot reach the Cycle server	Messages like "the cycle MCP server is not available," or Cycle tools never appear in the tool list.	Confirm cycle-cli.exe exists at C:\Program Files (x86)\CycleLabs\Cycle\cycle-cli.exe and that your MCP command points there; reinstall Cycle if the file is missing (installing Cycle). Fix JSON syntax—misplaced commas and unescaped \ in paths are common; use forward slashes as in Setup. Fully quit and reopen the agent host (Claude Code, Cursor, or VS Code) so edits to .mcp.json, .cursor/mcp.json, or .vscode/mcp.json load—MCP servers start only at startup.
Authentication failures during a run	run_test fails with unable to authenticate, invalid_grant, or similar. Uses the same credentials as cycle-cli and the desktop client; tokens can expire.	Ask the agent: "Authenticate with Cycle." It should call authenticate (browser login); finish login, then retry. If failures repeat in one session, log out and back into the desktop Cycle client to clear a stale token.
"Element not found" in a generated test	A .feature the agent wrote fails on click, type, or visibility because the locator matches nothing. Often the locator was written without inspecting the page.	Ask: "Open the failing page, take a snapshot, and rewrite the locator." Expect run_step to navigate, then run_step with WebDriver.snapshotPage to read the accessibility tree, then an updated locator in the .feature. If the agent skips snapshots, add a snapshot-first rule (Adding agent rules).
UnknownStep errors	UnknownStep: <step text> even when the line looks syntactically fine. The step is not in your installed step library—often the plugin that defines it is missing.	Have the agent search with search_steps for your <keyword> to find the correct step name or confirm it is missing. Install the plugin that provides the step (Step Plugins) and restart the agent.
MCP server works but plugin calls hang	Lightweight tools like cycle://categories succeed, while run_step or run_test sits until timeout. The first plugin call can take 10–30 seconds while the JVM warms; a short agent tool timeout can make that look like a hang.	Wait and retry; later calls usually return quickly. If hangs continue past the first call, add --debug to your MCP config (Server flags), reproduce, and inspect MCP / plugin logs in the agent host.
Agent says it wrote a file but disk is unchanged	The agent reports writing a .feature, but the file is empty or unchanged. Usually wrong working directory or write permissions—not a Cycle MCP defect.	Compare the path the agent reports with your real project location. Check write permissions on the folder (the default Test Cases/ tree inside a Cycle project should be writable; protected system paths may fail silently). Ask the agent to print the path it used and verify in Explorer.

Diagnostics with --debug

For any persistent issue, add --debug to your MCP config's args array. This forwards plugin stdout/stderr to the server's stderr, which most agent hosts surface in their MCP-server log:

Agent host	Where to find MCP logs
Claude Code	The Claude Code output panel in your IDE, or run claude mcp logs cycle from a terminal.
Cursor	Settings → MCP → click on the cycle server entry → view logs.
Copilot in VS Code	Output panel → select MCP from the dropdown.

Once you're done diagnosing, remove --debug to keep the logs quieter for normal use.

Asking for Help

If you hit a problem not covered here, please contact Cycle Labs support with:

• The text of the error message (or screenshot)
• The agent you're using (Claude Code, Cursor, or VS Code Copilot)
• The contents of your MCP config block (with paths but redact any tokens)
• The output from --debug if applicable

The support team can be reached at help.cyclelabs.io.