Cutover MCP (Model Context Protocol)

An MCP server for interacting with the Cutover API, powered by FastMCP.

Contents

• Capabilities

• Installation

• Setup

• Environment Configuration

  • Environment Variables Reference

  • Generating an API Token

• Security & Responsible Use

• Project Structure

• Notes

• Client Setup

• Docker Usage

• Example: Using Docker in MCP Server Configuration

• FAQs

• Troubleshooting

Related MCP server: Maverick MCP Server

Capabilities

The server exposes 35 tools over MCP, grouped into 13 categories.

Tool Groups

Tools

Runbooks

• workspace_id: The unique identifier for the workspace (string, required)

• is_template: Filter by template status — false excludes templates, true shows only templates (boolean, optional)

• archived: Filter by archived status — false excludes archived runbooks, true shows only archived (boolean, optional)

• source_runbook_id: Filter to only runbooks created from this template ID (string, optional)

• folder_id: Filter to only runbooks in this folder ID (string, optional)

• extra_params: Additional query parameters to pass to the API, e.g. {"stage": "active"} (object, optional)

• runbook_id: The unique identifier for the runbook (string, required)

• name: The name of the new runbook (string, required)

• workspace_id: The workspace to create the runbook in — required unless copy_source_runbook_id is passed (string, optional)

• description: Description for the runbook (string, optional)

• status: RAG status — off, red, amber, green (string, optional)

• is_template: Whether the runbook is a template (boolean, optional)

• template_type: off, default, or snippet (string, optional)

• rto: Recovery Time Objective in seconds (integer, optional)

• timezone: IANA timezone name (string, optional)

• runbook_type_id: Runbook type to associate (string, optional)

• rto_start_task / rto_end_task: Start/end task IDs for the RTO/RTA feature (string, optional)

• folder_id: Folder to place the runbook in — defaults to the workspace's default location (string, optional)

• custom_field_values: Custom field values to set, e.g. {"name": "Field Name", "value": "value"} (array of object, optional)

• master_template: Whether this runbook can generate app-specific templates — requires is_template=true, and the API rejects it otherwise; on rejection, surface it rather than silently setting is_template=true (boolean, optional)

• start_scheduled: ISO 8601 timestamp, or the literal "now", to schedule the start (string, optional)

• end_scheduled: ISO 8601 timestamp for the scheduled end — must be omitted if start_scheduled isn't set (string, optional)

• auto_start: Whether to auto-start once start_scheduled is reached (runs live, comms on) (boolean, optional)

• copy_source_runbook_id: ID of an existing runbook/template to copy from (string, optional)

• copy_tasks / copy_teams / copy_users: What to include in the copy — each defaults to true; teams copied without members unless copy_users is also true (boolean, optional)

• shift_fixed_times: When copying, recalculate fixed task times relative to the new runbook's start (boolean, optional)

• runbook_id: The unique identifier for the runbook (string, required)

• name / description: New name/description (string, optional)

• status: RAG status — off, red, amber, green (string, optional)

• is_template: Whether the runbook is a template (boolean, optional)

• rto: Recovery Time Objective in seconds (integer, optional)

• timezone: IANA timezone name (string, optional)

• rto_start_task / rto_end_task: Start/end task IDs for the RTO/RTA feature (string, optional)

• custom_field_values: Custom field values to update (array of object, optional)

• folder_id: Folder to move the runbook to (string, optional)

• master_template: Requires is_template=true; the API rejects it on a non-template runbook — surface the rejection instead of auto-flipping is_template (boolean, optional)

• start_scheduled / end_scheduled: ISO 8601 timestamps (or "now" for start) to (re)schedule the runbook (string, optional)

• auto_start: Whether to auto-start once start_scheduled is reached (boolean, optional)

• runbook_id: The unique identifier for the runbook (string, required)

• action: start, cancel, pause, or resume — the only supported actions (string, required)

• comms: off, test, on — start only (string, optional, default "off")

• disable_task_notify: Disable task start notifications — start only (boolean, optional)

• run_type: live or rehearsal — start only (string, optional, default "rehearsal")

• rebaseline: Recalculate all planned times based on current time — start only (boolean, optional)

• shift_fixed_times: Shift fixed-time tasks relative to current time — start only (boolean, optional)

• validation_level: warning or error — start only (string, optional, default "error")

• message: Note attached to the action — cancel/pause/resume only (string, optional)

• notify: Notify users about the action — cancel/pause/resume only (boolean, optional)

• runbook_id: The template runbook ID to find copies of (string, required)

Runbook Types

No parameters.

• runbook_type_id: The unique identifier for the runbook type (string, required)

• query: Case-insensitive text matched against the runbook type name, key, and description (string, optional)

• incident: Filter by whether the type is for incidents (boolean, optional)

• enable_rto: Filter by whether the type supports the RTO/RTA feature (boolean, optional)

• dynamic: Filter by whether the type is dynamic (boolean, optional)

• ai_create_enabled: Filter by whether AI-assisted creation is enabled for the type (boolean, optional)

• include_archived: Include archived runbook types; archived types are excluded by default (boolean, optional)

• include_disabled: Include disabled runbook types; disabled types are excluded by default (boolean, optional)

Tasks

• runbook_id: The unique identifier for the runbook (string, required)

• forecast: Return all tasks with computed timing (start_display/end_display) and dependency graph fields, overriding pagination/filters (boolean, optional)

• fields_task: Specific task fields to return, e.g. ["name", "stage"] (array of string, optional)

• stage: Filter by stage — default, startable, in_progress, complete (array of string, optional)

• stream_id: Filter to tasks in these stream IDs (array of string, optional)

• completion_type: complete_normal, complete_skipped, complete_abandoned, complete_auto (string, optional)

• task_type_id: Filter to tasks of these task type IDs (array of string, optional)

• level: Filter by task level (string, optional)

• search_term: Match against task name (string, optional)

• has_comments: Only return tasks that have comments (boolean, optional)

• runbook_team_id: Filter to tasks assigned to these runbook team IDs (array of string, optional)

• user_id: Filter to tasks assigned to these user IDs (array of string, optional)

• source_runbook_id: Filter to tasks originating from these source runbook IDs (array of string, optional)

• sort: Sort field, e.g. start_planned or -start_planned for descending (string, optional)

• runbook_id: The runbook to add the task to (string, required)

• name: Task name (string, required)

• description: Task description (string, optional)

• task_type_id: Task type to associate (string, optional)

• stream_id: Stream (or substream) to assign the task to (string, optional)

• predecessors: Task IDs that are predecessors to this task (array of string, optional)

• duration: Planned duration in seconds (integer, optional)

• task_links: Links to other resources — link_type="runbook" links to a template runbook (target must be a template with ≥1 task and the task's task_type_id must be the tenant's linked type, or the link is silently dropped); link_type="snippet" attaches snippets (array of object, optional)

• message: Message body for an Email/SMS/Call task, or initial prompt for an agentic task (string, optional)

• recipients: Recipients for a comms task (array of object, optional)

• assignees: Assignees to add — only users/teams already participating on the runbook are honored, others are silently ignored (array of object, optional)

• custom_field_values: Custom field values to set (array of object, optional)

• start_fixed / end_fixed: ISO 8601 timestamps fixing start/end (string, optional)

• level: level_1, level_2, or level_3 (string, optional, default level_3)

• auto_start: Start automatically once predecessors complete (boolean, optional)

• auto_finish: Complete automatically once started (boolean, optional)

• runbook_id / task_id: The runbook and task to update (string, required)

• name / description: New name/description (string, optional)

• predecessors: Task IDs that are predecessors to this task (array of string, optional)

• task_type_id: Task type to associate (string, optional)

• stream_id: Stream (or substream) to assign the task to (string, optional)

• duration: Planned duration in seconds (integer, optional)

• custom_field_values: Custom field values to update (array of object, optional)

• assignees: Assignees to add — only existing runbook participants are honored; additive by default (array of object, optional)

• delete_excluded_assignees: When true, replaces the full assignee list with only those provided instead of adding to it (boolean, optional, default false)

• task_links: Replaces the task's links entirely — pass an empty list to clear all links (array of object, optional)

• message: Message body for an Email/SMS/Call task, or initial prompt for an agentic task (string, optional)

• recipients: Recipients for a comms task (array of object, optional)

• start_fixed / end_fixed: ISO 8601 timestamps fixing start/end (string, optional)

• level: level_1, level_2, or level_3 (string, optional)

• auto_start / auto_finish: Auto-start on predecessor completion / auto-finish on start (boolean, optional)

• runbook_id / task_id: The runbook and task to start (string, required)

• runbook_id / task_id: The runbook and task to complete (string, required)

• runbook_id / task_id: The runbook and task to skip (string, required)

• comment: Reason for skipping — required by the API and posted as a runbook comment (string, required)

• runbook_id / task_id: The runbook and task to delete (string, required)

Task Types

No parameters.

Streams

• runbook_id: The runbook to list streams for (string, required)

• forecast: Include computed forecast fields (start_display, end_display, etc.) (boolean, optional)

• runbook_id / stream_id: The runbook and stream to fetch (string, required)

• runbook_id: The runbook to create the stream in (string, required)

• name: Stream name (string, required)

• description: Stream description (string, optional)

• color: CSS-friendly color, e.g. #f0f0f0 or rgb(0,0,0) (string, optional)

• parent_stream_id: Parent stream ID, if creating a substream (string, optional)

• runbook_id / stream_id: The runbook and stream to update (string, required)

• name / description / color: New values (string, optional)

• runbook_id / stream_id: The runbook and stream to delete (string, required)

Workspaces

• limit: Maximum workspaces to return (integer, optional, default 50)

• offset: Number of workspaces to skip (integer, optional, default 0)

• query: Search string (string, required)

• workspace_id: The unique identifier for the workspace (string, required)

• name: Workspace/account name (string, required)

• key: Shortened version of the name (string, required)

• description: Workspace/account description (string, optional)

Teams

• runbook_id: The runbook to fetch teams for (string, required)

Users

• user_id: The user ID to fetch (string, required)

• query: Search string — name or email, partial match (string, required)

Custom Fields

• workspace_id: Filter to a workspace — omit to return fields from all accessible workspaces (string, optional)

• include_global: When workspace_id is set, also include globally available fields alongside the workspace's own (boolean, optional, default true)

• scope: task, runbook, or all (string, optional, default "all")

• custom_field_id: The custom field to retrieve (string, required)

Folders

• workspace_id: The workspace to list folders for (string, required)

Comments

• runbook_id: The runbook to comment on (string, required)

• content: Comment text — a limited set of HTML tags is supported (e.g. <p>, <b>, <ul>, <code>); markdown is not rendered and disallowed tags are stripped (string, required)

• task_id: Task to attach the comment to — omit to post at runbook level (string, optional)

Activities

• runbook_id: The runbook to retrieve activities for (string, required)

• created_after / created_before: ISO 8601 date bounds (string, optional)

Action Logs

• runbook_id / user_id / workspace_id: Filter by runbook, user, or workspace (string, optional)

• created_after / created_before: ISO 8601 date bounds (string, optional)

• max_pages: Maximum pages to fetch — response flags truncated: true if more remain (integer, optional, default 10)

This includes both read and write tools — see Security & Responsible Use for how to scope access appropriately.

Installation

To set up the project, ensure you have the required dependencies installed. For macOS users, you can install uv using Homebrew:

brew install uv

This project requires Python 3.13+ — uv installs and manages the right interpreter automatically, so you don't need to install Python separately.

Setup

1. Copy .env.example to .env and fill in your Cutover API credentials — see Environment Configuration below.

2. Install dependencies with uv:

   uv sync

3. Run the server using:

   uv run python src/cutover_mcp/server.py

4. Run tests:

   uv run pytest

Environment Configuration

Environment Variables Reference

Generating an API Token

There are two ways to generate a token:

• Access Management — an admin generates a token for a specific user (useful if you want the token to act as someone other than yourself, e.g. a global admin, or you don't have self-service access).

• My Details → User App Tokens — generate your own token directly, self-service.

Security & Responsible Use

The MCP server adds no security model of its own — it authenticates to the Cutover API as a single user app token over HTTPS and inherits exactly that user's permissions. Scope the token correctly and use the write tools deliberately:

• Least privilege. Use a dedicated non-interactive user with the Developer role plus only the scoped roles the use case needs (e.g. Workspace manager on one workspace) — not a personal admin token. Rotate the token periodically and revoke it in Cutover when the use case ends.

• Read-only vs read-write. This server ships write tools (create_runbook, manage_runbook, delete_task, start_task, …) and does not enforce read-only itself. For query-only use cases, omit roles that grant create/update/delete/manage — least privilege is configured in Cutover, not the client.

• Approve writes. Keep human approval enabled for mutating or consequential actions — models can act on unexpected content returned by tools, so approval is the real safeguard.

• Verify critical output. A tool call returns real data, but the model's summary of it can still be wrong (or answer with no tool call at all). For compliance- or audit-critical output, verify against Cutover as the system of record.

• Protect the token. It lives in env config (.env* is git-ignored and excluded from Docker images). If a token is compromised, revoke it immediately in Cutover's Access Management — the MCP server holds no independent session, so revoking the token fully cuts off access, and a scoped role confines any impact to that use case.

Project Structure

• src/cutover_mcp/ - Main package

• clients/ - API client

• resources/ - Resource definitions (MCP endpoints)

• tools/ - Tool logic

• server.py - FastMCP server entrypoint

• tests/ - Tests

Notes

• Dependency and environment management is handled by uv and hatchling.

• Versioned releases and the changelog live under Releases. The server reports its version as serverInfo.version and from GET /health when running over HTTP.

Client Setup

Run in VS Code GitHub Copilot

If you want to use VS Code with GitHub Copilot to call out to this MCP server, you can use mcp.json.example.

1. Copy mcp.json.example to .vscode/mcp.json (create the .vscode/ directory if not already present)

2. Change the Users/YOUR-USER-NAME/... example path to point at your working directory instead (the example uses a macOS-style path — adjust the format for Windows if needed)

3. Restart VS Code for the changes to take effect. In the Copilot Chat box, click the Configure tools icon and expand cutover-mcp to see its full list of tools. MCP tools only run in Agent mode — switch the mode dropdown from Ask to Agent if nothing happens.

Run in Claude Desktop

If you'd rather use Claude Desktop instead of an IDE, you can set that up:

1. Download and install Claude Desktop.

2. Copy claude_desktop_config.json.example to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS path shown; on Windows, use %APPDATA%\Claude\claude_desktop_config.json).

3. Update the command and args paths in that file to point at your repo's .venv/bin/python and src/cutover_mcp/server.py.

4. Restart Claude Desktop. Click the + button at the bottom of the chat box, then Connectors — cutover-mcp should be listed there along with its tools. If it isn't, check Settings → Developer for its connection status and logs.

This will allow Claude Desktop to connect to your MCP server.

Docker Usage

Docker is optional — the server runs fine without it (see Setup). Use this if you want a self-contained way to run it instead of managing a venv.

From the repository root, build the image:

docker build -t cutover-mcp .

.env is excluded from the build via .dockerignore, so the image isn't tied to any environment or credential — never bake .env into an image you build, push, or share.

Pass your .env file in at run time instead, with --env-file:

docker run -i --rm --env-file .env cutover-mcp

Example: Using Docker in MCP Server Configuration

You can configure your MCP server to use the Docker container instead of the venv. The root key differs by client: VS Code (mcp.json) uses servers; Claude Desktop (claude_desktop_config.json) uses mcpServers.

VS Code (.vscode/mcp.json):

{
  "servers": {
    "cutover-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/path/to/your/repo/.env",
        "cutover-mcp"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cutover-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/path/to/your/repo/.env",
        "cutover-mcp"
      ]
    }
  }
}

To use Docker in the example configuration files (mcp.json.example and claude_desktop_config.json.example), replace the existing commands with the Docker-based commands shown in the "Docker Usage" section above.

FAQs

How can I start the MCP server via Visual Studio Code?

Open up the .vscode/mcp.json file. Hover above the name of the server i.e. 'cutover-mcp'. You should have the option to start the server.

Troubleshooting

Why is VS Code not giving me the ability to start the MCP server?

Ensure you aren't running the server independently in another terminal. Close and re-open VS Code, and if that doesn't work, restart your machine.

Alternatively, you can use the following approach to start the server:

View -> Command Palette -> MCP: List Servers -> your mcp server -> start/restart/stop server.