Octopus Deploy Official MCP Server

Create a new release for an Octopus Deploy project

This tool creates a new release for a project. The space name and project name are required. All other parameters are optional and will use Octopus defaults if not specified.

Deploy a release to one or more environments in Octopus Deploy

This tool supports both tenanted and untenanted deployments:

• Untenanted: Don't provide tenants or tenantTags. Can deploy to multiple environments at once.
• Tenanted: Provide tenants or tenantTags. Can only deploy to ONE environment, but can target multiple tenants.

The tool automatically determines which deployment type to use based on the parameters provided.

Reach Octopus REST endpoints not covered by the curated tools. Use this only after grep_llms_txt has shown you the right method and path.

Method gating is hard-coded server-side, three tiers:

• GET → read tier: always allowed (subject to toolset allowlist + sensitive denylist).
• POST/PUT/PATCH → write tier: blocked when --read-only is set; requires user confirmation via elicitation otherwise.
• DELETE → delete tier: requires --allow-deletes (and is blocked when --read-only is set) AND a stronger user confirmation.

The HTTP method enum is the gate. The tool will not honour any 'isRead' flag the agent invents — the runtime classifies based on the actual method.

Other gates (in order):

0. Path shape: must be '/api' or start with '/api/'. Absolute URLs, '~/api/...', '/octopus/portal/...', query strings, fragments, '..' segments, and percent-encoded slashes are all rejected up front.
1. Sensitive denylist: API key endpoints and catastrophic deletes (DELETE /api/users/{id}, DELETE /api/spaces/{id}) are always blocked.
2. Path allowlist — only applied when --toolsets has narrowed the active set. With every toolset enabled (the default, or explicit --toolsets all) any path under /api is reachable subject to the other gates; when toolsets are narrowed, paths only resolve if their owning toolset is enabled so disabling a toolset (e.g. 'certificates') makes its endpoints unreachable even on GET.
3. Elicitation on every non-GET, with a stronger message for DELETE.

Discover endpoints with grep_llms_txt. Use octopus://api/capabilities to see which toolsets are enabled and whether write/delete modes are on.

Find accounts in a space - can retrieve a single account by ID or list all accounts

This unified tool can either:

• Get detailed information about a specific account when accountId is provided
• List all accounts in a space when accountId is omitted

You can optionally filter by various parameters like name, account type, etc. when listing.

Find certificates in a space - can retrieve a single certificate by ID or list all certificates

This unified tool can either:

• Get detailed information about a specific certificate when certificateId is provided
• List all certificates in a space when certificateId is omitted

You can optionally filter by various parameters like name, archived status, tenant, etc. when listing.

Find deployment targets (machines) in a space - can retrieve a single target by ID or list all targets

This unified tool can either:

• Get detailed information about a specific deployment target when targetId is provided
• List all deployment targets in a space when targetId is omitted

You can optionally filter by various parameters like name, roles, health status, etc. when listing.

Search the Octopus Deploy audit log (also called the Events log) — every meaningful action recorded against a space: deployments, release creations, modifications, user logins, machine registrations, variable edits, tenant changes, and so on.

Modes (the mode arg):

• search (default) — query the audit log. Requires spaceName. Supports rich filtering by user, project, environment, tenant, document type, date range, category, group, and agent.
• listCategories — enumerate every event category (e.g. DeploymentSucceeded).
• listGroups — enumerate event groups (e.g. Created, Modified, Deleted, Deployment). Each group lists the categories inside it.
• listAgents — enumerate user-agent strings recorded by the audit subsystem.
• listDocumentTypes — enumerate entity-prefix metadata (Projects-, Releases-, ...).

Search modes (within mode='search', picked by argument shape):

• eventId → fetch that single event. Mutually exclusive with list and pagination filters; excludeDifference is still honoured.
• otherwise → list events matching the filters, paginated.

Performance tip: the per-event ChangeDetails field (the before/after diff for Modified events) is by far the heaviest payload field. Pass excludeDifference: true whenever scanning many events; fetch a single event without the flag when you need the diff.

Filter semantics:

• regarding — AND semantics: event must reference EVERY listed document ID.
• regardingAny — OR semantics: event must reference ANY listed document ID.
• All other multi-value filters (users, projects, environments, tenants, eventCategories, eventGroups, ...) are OR semantics within the field.
• from (inclusive) and to (exclusive) accept ISO 8601 datetimes.

Permissions: requires EventView on the calling user's space scope. The server filters results further based on per-document permissions.

List customer feature toggles in an Octopus Deploy project.

Each summary includes per-environment state (isEnabled, rolloutPercentage, clientRolloutPercentage) so "where is X turned on" is answerable from the list response. Heavy fields (description, tenant lists, segments, minimum versions) live in the resource body.

Dereference the returned resourceUri (octopus://spaces/{spaceName}/projects/{projectId}/featuretoggles/{slug}) for the full toggle body.

Use update_feature_toggle to flip an environment on/off or change rollout percentages on an existing toggle. This MCP server does not expose toggle creation, deletion, renaming, or rollout-group management — direct customers to the Octopus UI for those.

Find interruptions (manual interventions, guided failures, deployment approvals) in an Octopus Deploy space.

Interruptions are the Octopus surface equivalent to pending approvals: a deployment or runbook run pauses and waits for a human to take action. Use this tool to enumerate them or to look up a single one.

Modes (picked by which arguments you supply):

• interruptionId → fetch the slim summary for that interruption.
• assignedToMe → list interruptions the authenticated user can act on; resolves /users/me (cached per session).
• regarding → list interruptions related to a specific entity (ServerTasks-…, Deployments-…). Native server-side filter.
• (none) → list all interruptions, optionally filtered by pendingOnly (default: true) and skip/take.

Each summary includes:

• resourceUri → octopus://spaces/{spaceName}/interruptions/{id} for the FULL body (form definition with Markdown instructions, button options, control types, and any already-submitted values). Dereference this when the user asks for details about a specific interruption.
• taskResourceUri → octopus://spaces/{spaceName}/tasks/{taskId} for the surrounding deployment/runbook task.
• publicUrl → Octopus portal deep link to take action.
• formElementNames → just the field names (e.g. Instructions, Notes, Result). Field values are NOT in the slim summary; fetch resourceUri for those.

Find releases in an Octopus Deploy space.

Three modes, picked by which arguments are supplied:

• releaseId → fetch the summary for that release.
• projectId → list releases for that project (optionally filtered by searchByVersion).
• neither → list releases across the space.

Each summary includes a resourceUri for fetching the full release body (release notes, packages, build information, custom fields).

Find runbooks in an Octopus Deploy project.

Two project kinds are supported:

• DB-backed projects: address runbooks by 'runbookId' (e.g. 'Runbooks-123'). The summary includes 'publishedRunbookSnapshotId', which run_runbook uses by default.
• Config-as-Code (CaC) projects: pass 'gitRef' (branch name like 'main', tag, or commit SHA). Address a single runbook by 'runbookSlug'. The summary includes 'gitRef' instead of 'publishedRunbookSnapshotId'; run_runbook needs the same gitRef.

Modes:

• runbookId → fetch a single DB runbook.
• runbookSlug + gitRef → fetch a single CaC runbook.
• gitRef alone → list CaC runbooks at that ref.
• neither → list DB runbooks in the project (optionally filtered by partialName).

Each summary includes multiTenancyMode and environmentScope so callers can determine which environments and tenants are valid targets before invoking run_runbook.

Find tenants in a space - can retrieve a single tenant by ID or list all tenants

This unified tool can either:

• Get details for a specific tenant when tenantId is provided, including the projects and environments the tenant is associated with
• List all tenants in a space when tenantId is omitted

Tenants represent customers or clients in Octopus Deploy, allowing you to manage deployments and configurations specific to each tenant. Tenants can be grouped into tenant tags for easier management and deployment targeting. Tenants can also represent geographical locations, organizational units, or any other logical grouping.

Optionally provide filtering and pagination parameters when listing.

Get Git branches for a version-controlled project

This tool retrieves Git branches for a specific project in a space. The space name and project ID are required. Optionally provide searchByName, skip, and take parameters for filtering and pagination.

Get information about the current authenticated user

This tool retrieves information about the currently authenticated user from the Octopus Deploy API.

Get deployment details from an Octopus Deploy deployment URL. Returns comprehensive deployment information including the task ID needed to view execution logs.

Accepts deployment URLs like: https://your-octopus.com/app#/Spaces-1/projects/my-app/deployments/releases/1.0.0/deployments/Deployments-123

Returns:

• Full deployment details (environment, release, project, created time)
• taskIdForLogs: the ServerTasks- ID for this deployment
• taskResourceUri: octopus:// URI for the structured activity tree (resources/read or read_resource)
• grepTaskLogHint: pre-filled arguments for the grep_task_log tool — call it with a pattern to search the raw log without fetching the whole thing
• Public URL for web portal access

Recommended workflow for investigating deployment issues:

1. Call get_deployment_from_url with the deployment URL
2. Review deployment context (environment, release version, etc.)

3a. Fetch the taskResourceUri for the structured activity tree (step timings, embedded log entries by category), OR 3b. Call grep_task_log with the taskId to search the raw log for a specific error / pattern

Handles space ID to space name resolution automatically.

Get deployment process by ID

This tool retrieves a deployment process by its ID. Each project has a deployment process attached, and releases/deployments can also have frozen processes attached.

Get Kubernetes live status for a project and environment

This tool retrieves the live status of Kubernetes resources for a specific project and environment. Optionally include a tenant ID for multi-tenant deployments.

Get missing tenant variables

This tool retrieves tenant variables that are missing values. Optionally filter by tenant, project, or environment.

Get task details from an Octopus Deploy task URL. Returns full task details including execution logs and state.

This tool is a URL-to-ID resolver that returns the same body as the octopus://spaces/{spaceName}/tasks/{taskId}/details resource — no need to dereference the URI afterward. If you only need lightweight metadata for polling (state, timing, completion flags) use the smaller octopus://spaces/{spaceName}/tasks/{taskId} resource instead.

Accepts task URLs like: https://your-octopus.com/app#/Spaces-1/tasks/ServerTasks-456

Key features:

• Returns full task details including execution logs
• Handles space ID to space name resolution automatically
• Validates task ID format

For deployment URLs: If you have a deployment URL, use this workflow:

1. Call get_deployment_from_url with the deployment URL
2. Use the returned taskResourceUri (structured tree) or call grep_task_log with the returned taskId to search the raw log

Tasks represent background operations in Octopus Deploy, such as deployments, health checks, and system maintenance. Each task has a unique ID and can be monitored for status and progress.

Get tenant variables by type

This tool retrieves different types of tenant variables. Use variableType parameter to specify which type:

• "all": Get all tenant variables
• "common": Get common variables only
• "project": Get project-specific variables only

This tool gets all project and library variable set variables for a given project. Projects can contain variables (specific to a project), library variable sets (shared collections of variables associated with many projects), and tenant variables (variables related to a tenants connected to the project) If you want to retrieve tenant variables for a tenant connected to the project, use the get_tenant_variables tool.

Search the Octopus API catalog at octopus://api/llms.txt with grep-style semantics. The catalog is large (~300+ KB) — call this rather than reading the resource body directly.

llms.txt is structured as:

• Authentication and Space Selection sections (top of file)
• Endpoints section: one '### {Category}' heading per resource family (Accounts, ActionTemplates, Channels, Releases, …) and one bullet per endpoint of the form - METHOD /path - description | Prefixes (pick one): /{spaceId}, /spaces/{spaceIdentifier} | ?queryParams → ReturnType
• Steps section: deployment step types (Octopus.* ActionType) and their configurable property keys.

Useful patterns:

• 'POST /releases' — find write endpoints under a resource family
• 'DELETE ' — enumerate delete endpoints
• '### Channels' — jump to a section heading
• 'Body: Create.*Command' — find endpoints that take a Create command body

Parameter conventions mirror GNU grep:

• pattern (regex by default; set fixedString:true for literal text)
• caseInsensitive (-i)
• invertMatch (-v)
• fixedString (-F)
• beforeContext (-B)
• afterContext (-A)
• maxCount (-m)

Response: totalMatches (true count across the whole file), totalLines, the matched lines with 1-indexed lineNumber, optional before/after context arrays, and catalogResourceUri for the structured fall-through.

Search a server task's activity log with grep-style semantics. Returns only matching lines (with optional symmetric context windows). This is the canonical way to inspect task logs — there is no full-log resource URI, because exposing one would tempt callers to inhale multi-megabyte bodies when grep is almost always the better primitive.

Use this when you know what to look for (a specific error string, a step name, a pattern). For structured access to the activity tree (step hierarchy, categories, timing) use the octopus://spaces/{spaceName}/tasks/{taskId}/details resource instead.

Parameter conventions mirror GNU grep so the schema is self-explanatory:

• pattern (regex by default; set fixedString:true for literal text)
• caseInsensitive (-i)
• invertMatch (-v)
• fixedString (-F)
• beforeContext (-B)
• afterContext (-A)
• maxCount (-m)

Response includes totalMatches (true count across the whole log), totalLines, the matched lines with 1-indexed lineNumber, optional before/after context arrays, and a taskDetailsResourceUri for the structured fall-through.

List deployments in a space

This tool lists deployments in a given space. The space name is required. When requesting latest deployment consider which deployment state the user is interested in (successful or all). Optional filters include: projects (array of project IDs), environments (array of environment IDs), tenants (array of tenant IDs), channels (array of channel IDs), taskState (one of: Canceled, Cancelling, Executing, Failed, Queued, Success, TimedOut), and take (number of results to return).

List environments in a space

This tool lists all environments in a given space. The space name is required. Use this tool as early as possible to understand which environments are configured. Optionally filter by partial name match using partialName parameter.

This tool lists all projects in a given space. Projects let you manage software applications and services, each with their own deployment process, lifecycles, and variables. Projects are where you define what you are deploying and how it should be deployed. The space name is required, if you can't find the space name, ask the user directly for the name of the space. Optionally filter by partial name match using partialName parameter.

List all spaces in the Octopus Deploy instance. Spaces is the main organizational unit in Octopus Deploy, Spaces keep the different projects, infrastructure and tenants completely separate. Spaces typically represent team or project boundary, but not customer boundary (use tenants for those). Always use this tool first to check that the requested space exists.

Universal fetch for any 'octopus://' URI returned by any other tool. Use this whenever you see fields like 'resourceUri' or 'taskResourceUri' in a response and need the full body.

How to use:

• Pass the URI string verbatim. Examples: 'octopus://spaces/Default/releases/Releases-42', 'octopus://spaces/Default/tasks/ServerTasks-7', 'octopus://spaces/Default/tasks/ServerTasks-7/details'.
• The response 'mimeType' tells you how to interpret 'text': 'application/json' → parse as JSON.

This tool is the backstop for clients that do not natively implement the MCP 'resources/read' primitive. Clients that DO support resources/read (Claude Code, MCP Inspector) can call it directly and skip this tool. Either path returns byte-identical bodies.

Tools that return resource URIs include: find_releases, get_deployment_from_url, get_task_from_url, and others. When in doubt, call read_resource on any 'octopus://' string you encounter.

Note: there is intentionally no octopus://...tasks/{id}/log resource. Call the grep_task_log tool to search task logs without inhaling the full body.

Run a runbook against one or more environments in Octopus Deploy.

Runbooks execute operational processes (DB backups, smoke tests, environment refresh, etc.) against the specified environments. For tenanted runs, supply tenants and/or tenantTags.

Two project kinds:

• DB-backed projects: by default the runbook's published snapshot is used; pass runbookSnapshotId to pick a specific snapshot.
• Config-as-Code projects: pass gitRef (branch name like 'main', tag, or commit SHA). Snapshots don't apply — the gitRef is the version pin. Use find_runbooks with the same gitRef to discover runbook names.

Adjust an existing customer feature toggle in an Octopus Deploy project.

Narrow surface — flip an environment on/off, change rollout percentages, or update the toggle-level description / default state. Internally fetches the current toggle, applies your patches in memory, and PUTs the merged body, so unmentioned environments and unmentioned fields are preserved.

Deliberately not exposed: name/slug rename, tag changes, rollout group attach/detach, tenant targeting, segments, minimum version, adding or removing environment configurations entirely. For those, use the Octopus UI.

Patches that reference an environment not already configured on the toggle are rejected with reason: environment_not_configured. The tool does not add new environment configurations.