Rules

After you connect a coding agent to the Cycle MCP Server, you can add instruction files that steer how the agent uses Cycle. Rules remind the agent when to call Cycle tools, reduce repeated permission prompts, and keep writes under approved paths.

Why add rules and permissions?

The rules and permissions provided on this page improve outcomes for standard Cycle projects. Without rules and host permissions, the agent may guess locators, ask for approval on many ordinary Cycle MCP calls, or write into folders you meant to protect. Rules express preferred behavior at the level of intent. Permission settings make safe reads and writes quieter, and they block edits where they should not happen.

Choosing an instruction file

Each agent reads its own instruction file:

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.

The guidance below applies equally to all three. Cycle has no host-specific instruction file, so there is nothing Cycle-side to keep in step with your agent.

Writing rules that age well

Write rules at the level of intent rather than identifiers. Intent stays true across releases. Identifiers do not.

• Good: "Inspect the live page before writing a web locator."
• Risky: naming the specific tool and step to call.

For anything the agent needs to look up, point it at cycle://toc. That resource is the server's own table of contents. It lists every available resource with a short summary and a hint about when to read it, and it is generated from the live catalog, so it is always current for the version you have installed.

Reading cycle://toc requires signing in

Every Cycle resource requires a signed-in session. If the agent reads cycle://toc before you have signed in, it receives an authentication error naming the authenticate tool. That is expected behavior rather than a configuration problem. See Signing in to Cycle.

Do not paste a list of Cycle tools or resource URIs

An instruction file you write is yours alone. Cycle never updates it, so a list of cycle:// URIs or MCP tool names copied into it becomes a permanent snapshot. The Cycle MCP surface changes between releases, and installing a newer Cycle cannot correct a file it does not own. A stale list fails silently: the agent insists on capabilities that no longer exist.

Adding rules for Cycle projects

The rules below instruct the coding agent to prefer free read tools, use Cycle MCP for authoring, and write only under approved paths. By guiding the agent toward and away from certain tools, you can reduce prompts related to read and write permissions. They are especially helpful when working on conventional Cycle projects such as libraries.

The example below is for Claude Code (CLAUDE.md). It uses Claude Code's mcp__cycle__<tool> tool-name convention. Other agents use different file names and permission models, but the same intent applies: prefer Cycle MCP for Feature File work, allow safe reads and approved writes, and deny edits under protected folders such as Base\. Adapt the file extension and the tool-name prefix to match your agent's MCP namespacing convention.

# Cycle MCP rules

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

- Sign in first: if a Cycle call returns "authentication required," call `mcp__cycle__authenticate` and retry.
- 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.
- Do not use keys like TAB to navigate from field to field; use locators.
- To find unfamiliar step syntax, read the `cycle://steps` catalog (and `cycle://steps/{category}`), then read `cycle://step/{id}` for exact parameters. Do not rely on memory. Do not use any deprecated steps.
- Always call `mcp__cycle__validate_feature` before `mcp__cycle__run_test` to catch syntax errors cheaply.
- After a failed `run_test`, read the `cycle://run-errors/{output_dir}` resource to get structured error details. Percent-encode the `dbDir` it returned before inserting it into the URI: : → %3A, \ → %5C. Never place a raw Windows path in an MCP resource URI.
- Read `cycle://subagents/feature-file-author` once before writing any feature, and again before any web locator work (it includes locator formats).
- When reading `cycle://run-errors/…`, percent-encode the dbDir from run_test before inserting it into the URI: : → %3A, \ → %5C. Never place a raw Windows path in an MCP resource URI.
- Read `cycle://subagents/feature-file-author` once before writing any feature, and `cycle://subagents/locator-formats` before any web locator work.

# Prompt rules

## Free

Prefer these. Use a dedicated tool wherever one exists.

- `Glob`, `Grep`, `Read` in-tree
- `cycle://` resources
- `mcp__cycle__` `validate_feature`, `run_step`, `run_test`, `scenario_search`,
  `assign_variables`, `wms_validate_dynamic_tokens`
- `WebFetch` on `manual.cyclelabs.io`

## Prompts

- any shell call
- any other `mcp__cycle__` tool
- any other domain
- any write outside the list below
- `mcp__cycle__authenticate` prompts once - still call it on "authentication required"
- report missing rules; editing `.claude/settings.json` prompts too

## Writable

- `Test Cases\Custom\`
- `Utilities\Custom\`
- `Playlists\Custom\`
- `Data\Locators\**\Custom\`
- `Test Case Inputs\`
- `MCP Prompt Logs\`
- `Base\` is blocked outright - never write there
- new file at a new path: `Write` alone, it creates parent folders. No `mkdir`, `touch`, or `New-Item`.

## Screenshots

- `saveScreenshotWithFilePath`, absolute path under `MCP Prompt Logs\<TEST-ID>\screenshots\`
- never the session scratchpad
- shipped `.feature` files keep `Then I save web browser screenshot`, no path

Adjusting project permissions

Coding agents typically require users to provide approvals for tools to run. They frequently raise requests for approvals in the prompt while running. Although these kinds of requests are typical, they are pesky and can slow down the development process. Instead of approving each request piecemeal, you can set permissions to automatically allow certain tools to run or certain file paths to be edited.

Claude Code's .claude/settings.json in the project grants or denies permissions for specific tools.

• If a tool is allowed, Claude Code does not ask for permission before using it.
• If a tool is denied, Claude Code does not attempt it.

Use the settings file below to grant permissions to common tools and file paths for Cycle projects:

{
  "permissions": {
    "allow": [
      "ReadMcpResourceTool",
      "ListMcpResourcesTool",
      "ReadMcpResourceDirTool",
      "mcp__cycle__*",
      "WebFetch(domain:manual.cyclelabs.io)",
      "Edit(./Test Cases/Custom/**)",
      "Write(./Test Cases/Custom/**)",
      "Edit(./Utilities/Custom/**)",
      "Write(./Utilities/Custom/**)",
      "Edit(./MCP Prompt Logs/**)",
      "Write(./MCP Prompt Logs/**)",
      "Edit(./Data/Locators/**/Custom/**)",
      "Write(./Data/Locators/**/Custom/**)",
      "Edit(./Playlists/Custom/**)",
      "Write(./Playlists/Custom/**)",
      "Edit(./Test Case Inputs/**)",
      "Write(./Test Case Inputs/**)"
    ],
    "ask": [
      "mcp__cycle__moca_exec",
      "mcp__cycle__blueprint_teardown",
      "mcp__cycle__formulation_moca_finalize-tests-live",
    ],
    "deny": [
      "Edit(./Test Cases/Base/**)",
      "Write(./Test Cases/Base/**)",
      "Edit(./Utilities/Base/**)",
      "Write(./Utilities/Base/**)",
      "Edit(./Playlists/Base/**)",
      "Write(./Playlists/Base/**)",
      "Edit(./Data/Locators/**/Base/**)",
      "Write(./Data/Locators/**/Base/**)"
    ]
  }
}

Allowlists bypass confirmation prompts

Granting permissions for tools and paths lets the coding agent create, edit, or delete matching files without asking first. Those changes can be difficult or impossible to reverse if they are not already under source control. Review the allow and deny lists carefully, keep writable paths as narrow as you can, and commit or back up work you care about before you rely on auto-approved writes.

Pre-building host subagents

Coding agents can spawn a subagent: a focused child agent for a specific task. That keeps token use lower and context tighter than doing every search in the main conversation.

Not every project setting reaches every subagent. CLAUDE.md is one example that often does not carry over. Claude Code commonly creates built-in subagents named Explore or Plan. Because those names are known in advance, you can pre-build matching behavior files under .claude/agents/ in the project.

The following example creates .claude/agents/Explore.md for read-only search of a Cycle project. This host Explore agent is separate from Cycle MCP's own Agents served at cycle://subagents/{name}.

---
name: Explore
description: Fast read-only search of this Cycle project. Use for file discovery, locating scenarios and locators, and understanding project structure without making changes.
tools: Read, Grep, Glob, Bash
permissionMode: auto
model: inherit
---

You perform read-only exploration of a Cycle project.

## Search order

- `Grep` for content, `Glob` for file discovery, `Read` for contents. These are
  pre-approved and cost the user nothing.
- Reach for Bash only when Grep and Glob genuinely cannot do the job, such as
  deduplicating or aggregating across many matches. Prefer several Grep calls
  over one shell pipeline.

## Project layout

- `Test Cases\`, `Utilities\`, `Playlists\`, and `Data\Locators\` each split into
  `Base\` (vendor-shipped) and `Custom\` (local work).
- `Datasets\Base\**\*.msql` holds MOCA command definitions.
- `MCP Prompt Logs\` holds authoring logs and screenshots.
- `cycle://` MCP resources are pre-approved; read them freely.

## Never

- Write, edit, or delete anything. Report findings only.
- Read or write outside the project directory.

Report file paths with line numbers so the main agent can read them directly.

Putting the pieces together

With these project files in place, Claude Code prompts far less often while authoring through the Cycle MCP Server:

• CLAUDE.md at the project root
• .claude/settings.json
• .claude/agents/Explore.md

Other coding agents use different folder layouts and permission files. Similar customizations still apply: point the agent at Cycle MCP, allow safe reads and approved writes, and protect folders such as Base\.