diff --git a/public/docs/img/octopus-ai/mcp/claude-screenshot.webp b/public/docs/img/octopus-ai/mcp/claude-screenshot.webp new file mode 100644 index 0000000000..ba02731b5b Binary files /dev/null and b/public/docs/img/octopus-ai/mcp/claude-screenshot.webp differ diff --git a/public/docs/img/octopus-ai/mcp/mcp-settings.png b/public/docs/img/octopus-ai/mcp/mcp-settings.png new file mode 100644 index 0000000000..b46b59ddd6 Binary files /dev/null and b/public/docs/img/octopus-ai/mcp/mcp-settings.png differ diff --git a/src/pages/docs/octopus-ai/mcp/index.md b/src/pages/docs/octopus-ai/mcp/index.md new file mode 100644 index 0000000000..0678a60579 --- /dev/null +++ b/src/pages/docs/octopus-ai/mcp/index.md @@ -0,0 +1,26 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2025-04-04 +modDate: 2026-08-17 +title: Octopus MCP +navTitle: Overview +navSection: Octopus MCP +description: Connect AI assistants to Octopus Deploy with the remote or local Octopus MCP server. +navOrder: 2 +--- + +The Octopus Model Context Protocol (MCP) server connects AI assistants to your Octopus Deploy instance. It gives assistants tools to inspect and query your Octopus resources, diagnose problems, and perform supported tasks. + +## Octopus Remote MCP + +[Octopus Remote MCP](/docs/octopus-ai/mcp/remote) is hosted by your Octopus Deploy instance. It removes the need to install and manage the Octopus MCP server on your own machine and receives the latest MCP tools and features. + +## Local MCP + +[Local MCP](/docs/octopus-ai/mcp/local) runs as a package on your machine. The local server remains available for existing workflows, but it won't receive new features. + +## Related links + +- [Model Context Protocol](https://modelcontextprotocol.io/introduction) +- [Octopus Remote MCP](/docs/octopus-ai/mcp/remote) +- [Local MCP](/docs/octopus-ai/mcp/local) diff --git a/src/pages/docs/octopus-ai/mcp/index.mdx b/src/pages/docs/octopus-ai/mcp/index.mdx deleted file mode 100644 index a374d9dc23..0000000000 --- a/src/pages/docs/octopus-ai/mcp/index.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -layout: src/layouts/Default.astro -pubDate: 2025-04-04 -modDate: 2026-06-19 -title: Octopus MCP -navTitle: Overview -navSection: Octopus MCP -description: An overview of the the Octopus MCP server, allowing AI clients to leverage the power of Octopus Deploy -navOrder: 2 ---- - -## Octopus MCP Server - -The Octopus MCP ([Model Context Protocol](https://modelcontextprotocol.io/)) server represents a significant leap forward in AI integration capabilities. Built on Anthropic's open standard for connecting AI assistants to external data sources and tools, the MCP server enables AI assistants like Claude to interact directly with your Octopus Deploy infrastructure. - -The Octopus MCP server provides similar capabilities to the Octopus AI Assistant, but provides further benefits: - -- You can use it with your client and model of choice. -- It can work alongside other MCP servers to accomplish more complex orchestrations across Octopus and your other essential software services. - -The MCP server provides tools designed to solve key use-cases within change management, troubleshooting, administration audit & compliance, and standardization at scale. - -The MCP server architecture ensures that your deployment data remains secure while enabling powerful AI-assisted workflows. All interactions are logged and auditable, maintaining the compliance and governance standards your organization requires. - -The Octopus MCP Server is open source, and anyone can contribute to it. It's available for free on Github at [https://github.com/OctopusDeploy/mcp-server](https://github.com/OctopusDeploy/mcp-server) - -## Security - -The Octopus MCP Server works by communicating with your Octopus instance's REST API via a secure HTTPS connection. It leverages Octopus Server's existing API Key security mechanism, ensuring all interactions are authenticated, authorized for the permissions associated with the API Key, and audited. - -To learn more, read our [Octopus REST API](/docs/octopus-rest-api) documentation. - -## Governance - -Use dedicated [Agent API keys](/docs/octopus-rest-api/how-to-create-an-api-key#creating-an-agent-api-key) and [Agent Service Accounts](/docs/security/users-and-teams/service-accounts#agent-service-accounts) for agents connecting to your Octopus instance. These keep agent actions fully auditable in clear, filterable audit logs, so you can meet your compliance requirements. - -## 🚀 Installation - -### Requirements - -- Node.js >= v20.0.0 -- Octopus Deploy instance that can be accessed by the MCP server via HTTPS -- Octopus Deploy API key (we recommend creating a dedicated [Agent Service Account](/docs/security/users-and-teams/service-accounts#agent-service-accounts) and generating an [agent API key](/docs/octopus-rest-api/how-to-create-an-api-key#creating-an-agent-api-key) under it — this gives the MCP server its own identity, scopes its permissions, and makes its activity identifiable in the audit log and on the API Keys page) - -### Configuration - -Full example configuration (for Claude Desktop, Claude Code, and Cursor): - -```json -{ - "mcpServers": { - "octopusdeploy": { - "type": "stdio", - "command": "npx", - "args": ["-y", "@octopusdeploy/mcp-server"], - "env": { - "OCTOPUS_SERVER_URL": "https://your-octopus.com", - "OCTOPUS_API_KEY": "YOUR_API_KEY" - } - } - } -} -``` - -The Octopus MCP Server is typically configured within your AI Client of choice. - -It is packaged as an npm package and executed via Node's `npx` command. Your configuration will include the command invocation `npx`, and a set of arguments that supply the Octopus MCP Server package and provide the Octopus Server URL and API key required, if they are not available as environment variables. - -The command line invocation you will be configuring will be one of the two following variants: - -```bash -npx -y @octopusdeploy/mcp-server -``` - -With configuration provided via environment variables: - -```bash -OCTOPUS_API_KEY=API-KEY -OCTOPUS_SERVER_URL=https://your-octopus.com -``` - -Or with configuration supplied via the command line: - -```bash -OCTOPUS_API_KEY=API-KEY \ -npx -y @octopusdeploy/mcp-server --server-url https://your-octopus.com -``` - -For detailed documentation visit [the official Github repo](https://github.com/OctopusDeploy/mcp-server). diff --git a/src/pages/docs/octopus-ai/mcp/local/index.md b/src/pages/docs/octopus-ai/mcp/local/index.md new file mode 100644 index 0000000000..0364a205c4 --- /dev/null +++ b/src/pages/docs/octopus-ai/mcp/local/index.md @@ -0,0 +1,85 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2025-04-04 +modDate: 2026-08-17 +title: Local Octopus MCP server +navTitle: Overview +navSection: Local MCP +description: Install and run the local Octopus MCP server to connect AI clients to Octopus Deploy. +navOrder: 2 +--- + +The local Octopus MCP server connects AI assistants to your Octopus Deploy infrastructure. It uses [Model Context Protocol](https://modelcontextprotocol.io/introduction), an open standard for connecting AI assistants to external data sources and tools. + +The local MCP server provides similar capabilities to the Octopus AI Assistant, with some additional benefits: + +- You can use it with your client and model of choice. +- It can work alongside other MCP servers to coordinate tasks across Octopus and your other software services. + +The server provides tools for change management, troubleshooting, administration, audit and compliance, and standardization at scale. + +The local Octopus MCP server remains available for existing workflows, but it won't receive new features. For the latest tools and features without a local installation, use [Octopus Remote MCP](/docs/octopus-ai/mcp/remote). + +The local Octopus MCP server is open source and available from the [Octopus MCP server GitHub repository](https://github.com/OctopusDeploy/mcp-server). + +## Security + +The local Octopus MCP server communicates with your Octopus instance's REST API over HTTPS. It uses Octopus Server's API key security, so interactions are authenticated, limited to the permissions associated with the API key, and audited. + +For more information, see the [Octopus REST API](/docs/octopus-rest-api) documentation. + +## Governance + +Use dedicated [Agent API keys](/docs/octopus-rest-api/how-to-create-an-api-key#creating-an-agent-api-key) and [Agent Service Accounts](/docs/security/users-and-teams/service-accounts#agent-service-accounts) for agents connecting to your Octopus instance. These make agent actions identifiable and filterable in the audit log. + +## Installation + +### Requirements + +- Node.js 20 or later +- An Octopus Deploy instance that the MCP server can access over HTTPS +- An Octopus Deploy API key. We recommend creating a dedicated [Agent Service Account](/docs/security/users-and-teams/service-accounts#agent-service-accounts) and generating an [Agent API key](/docs/octopus-rest-api/how-to-create-an-api-key#creating-an-agent-api-key) for it. This gives the MCP server its own identity, limits its permissions, and identifies its activity in the audit log and on the API Keys page. + +### Configuration + +The following example configures the server for Claude Desktop, Claude Code, and Cursor: + +```json +{ + "mcpServers": { + "octopusdeploy": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@octopusdeploy/mcp-server"], + "env": { + "OCTOPUS_SERVER_URL": "https://your-octopus.com", + "OCTOPUS_API_KEY": "YOUR_API_KEY" + } + } + } +} +``` + +Configure the local Octopus MCP server in your chosen AI client. The server is published as an npm package and runs through Node.js with `npx`. The configuration must provide the Octopus Server URL and API key as environment variables or command-line arguments. + +Run the server with configuration supplied through environment variables: + +```bash +OCTOPUS_API_KEY=API-KEY \ +OCTOPUS_SERVER_URL=https://your-octopus.com \ +npx -y @octopusdeploy/mcp-server +``` + +Alternatively, supply the server URL as a command-line argument: + +```bash +OCTOPUS_API_KEY=API-KEY \ +npx -y @octopusdeploy/mcp-server --server-url https://your-octopus.com +``` + +For detailed configuration information, see the [Octopus MCP server GitHub repository](https://github.com/OctopusDeploy/mcp-server). + +## Related links + +- [Local MCP use cases](/docs/octopus-ai/mcp/local/use-cases) +- [Octopus Remote MCP](/docs/octopus-ai/mcp/remote) diff --git a/src/pages/docs/octopus-ai/mcp/local/use-cases.md b/src/pages/docs/octopus-ai/mcp/local/use-cases.md new file mode 100644 index 0000000000..df23c16065 --- /dev/null +++ b/src/pages/docs/octopus-ai/mcp/local/use-cases.md @@ -0,0 +1,70 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2025-04-04 +modDate: 2026-08-17 +title: Local MCP use cases +navTitle: Use cases +description: Example prompts for change management, troubleshooting, administration, audit, and compliance with Local MCP. +navOrder: 3 +--- + +These examples are a starting point for using the local Octopus MCP server. + +## Change management + +Reason about which changes have been deployed and where. This can help you understand which software versions your customers use in production. + +### Production version tracking + +Find the software version that a customer, represented by a tenant, is running in Production. You can also identify issues with their most recent deployment. + +**Example prompt** + +```text +Customer X has submitted a support ticket reporting a bug in the latest release of App. Which release are they using, when was it deployed, and were there any issues with the deployment? +``` + +## Troubleshooting + +Investigate failed deployments or unhealthy deployment targets to help restore service faster. + +### Deployment health analysis + +Check for failed deployments or unhealthy Kubernetes workloads, analyze the reasons for failure, and suggest solutions. + +**Example prompt** + +```text +Check the health of the {ServiceName} service in the {SpaceName} space and report any issues. Check the status of Kubernetes services to produce a comprehensive report. +``` + +Prompt for Kubernetes status to trigger a Kubernetes [live object status](/docs/kubernetes/live-object-status) check. + +## Administration, audit, and compliance + +Inspect your Octopus instance to help keep deployments healthy and configurations compliant. + +### Certificate expiry monitoring + +Identify unhealthy resources, expiring certificates, or unused projects in your Octopus instance. + +**Example prompt** + +```text +Find certificates in the {SpaceName} space that will expire soon. +``` + +### Resource access validation + +Find configured resources in your Octopus instance and check whether they can access the required targets. + +**Example prompt** + +```text +Check the accounts configured in the {SpaceName} space in my Octopus instance. Find the preproduction Azure account, then use the Azure MCP server to check which resources are available in that subscription. +``` + +## Related links + +- [Local Octopus MCP server](/docs/octopus-ai/mcp/local) +- [Octopus Remote MCP](/docs/octopus-ai/mcp/remote) diff --git a/src/pages/docs/octopus-ai/mcp/remote/index.md b/src/pages/docs/octopus-ai/mcp/remote/index.md new file mode 100644 index 0000000000..9aff8ed767 --- /dev/null +++ b/src/pages/docs/octopus-ai/mcp/remote/index.md @@ -0,0 +1,94 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-08-17 +modDate: 2026-08-17 +title: Octopus Remote MCP +navTitle: Remote MCP +navSection: Octopus Remote MCP +description: Connect AI assistants to your Octopus instance with the hosted Octopus Remote MCP server. +navOrder: 1 +--- + +Octopus Remote MCP connects the AI assistants you use in your day-to-day work to your Octopus Deploy instance. It gives those assistants access to Octopus tools and information through a standardized protocol. + +## Model Context Protocol + +[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open standard that connects AI assistants, such as Claude Code and ChatGPT, to the systems and services you own. These connections let assistants retrieve information and perform tasks across those systems and services. + +## Octopus Remote MCP server + +The Octopus Remote MCP server provides tools that let an AI assistant inspect and query resources in your Octopus instance and help diagnose problems. This turns your assistant into a DevOps partner that can work with the deployment information already in Octopus. + +The remote server runs in your Octopus Deploy instance, so you don't need to install the MCP server locally or manage server versions. New tools and features will be delivered through the remote server. + +The [local Octopus MCP server](/docs/octopus-ai/mcp/local) will remain available for the foreseeable future, but it won't receive new features. + +:::figure +![Sample MCP session](/docs/img/octopus-ai/mcp/claude-screenshot.webp) +::: + +## Available tools + +Octopus Remote MCP exposes a different set of tools from [Local MCP](/docs/octopus-ai/mcp/local). Its tools have two layers: + +- Dedicated tools for common operations, such as `find_spaces` and `find_projects`. +- Contract tools that provide access to selected Octopus REST API operations. The AI assistant uses `search_contracts` to find a contract, `describe_contract` to inspect its schema, and then `execute_query` for read operations or `execute_command` for operations that make changes. + +Octopus Remote MCP initially supports a selected set of core Octopus features. We'll add more operations to the contract tools over time. + +## Getting Started + +### Requirements +- An Octopus Deploy instance that can be accessed over HTTPS +- An Octopus Deploy API key. We recommend creating a dedicated [Agent Service Account](/docs/security/users-and-teams/service-accounts#agent-service-accounts) and generating an [Agent API key](/docs/octopus-rest-api/how-to-create-an-api-key#creating-an-agent-api-key) for it. This gives the MCP server its own identity, limits its permissions, and identifies its activity in the audit log and on the API Keys page. + +Set the `OCTOPUS_API_KEY` environment variable to your Agent API key, then run: + +```bash +claude mcp add --transport http \ + --header "X-Octopus-ApiKey:${OCTOPUS_API_KEY}" \ + octopus-deploy https://your-octopus-instance.com/mcp +``` + +Or in JSON format: +```json +"mcpServers": { + "octopus-deploy": { + "type": "http", + "url": "https://your-octopus-instance.com/mcp", + "headers": { + "X-Octopus-ApiKey": "${OCTOPUS_API_KEY}" + } + } +}, +``` + +### OAuth Support + +OAuth authentication flow is planned for a future release. + +## Security + +The Octopus MCP server operates within the same security boundary as our Rest API - user permissions still apply the same way. + +## Governance + +Use dedicated [Agent API keys](/docs/octopus-rest-api/how-to-create-an-api-key#creating-an-agent-api-key) and [Agent Service Accounts](/docs/security/users-and-teams/service-accounts#agent-service-accounts) for agents connecting to your Octopus instance. These make agent actions identifiable and filterable in the audit log. + +## Configuration + +Optionally, both the Remote MCP and the Local MCP can be disabled from **Configuration -> Settings -> MCP Controls** page. + +:::figure +![MCP Settings](/docs/img/octopus-ai/mcp/mcp-settings.png) +::: + +:::div{.warning} +Disabling the Local MCP will block incoming requests with the specific user agent string. A rogue AI agent could potentially replace this string with a different value and bypass the restriction. +::: + +## Related links + +- [Octopus Remote MCP use cases](/docs/octopus-ai/mcp/remote/use-cases) +- [Local MCP](/docs/octopus-ai/mcp/local) +- [Model Context Protocol](https://modelcontextprotocol.io/introduction) diff --git a/src/pages/docs/octopus-ai/mcp/remote/use-cases.md b/src/pages/docs/octopus-ai/mcp/remote/use-cases.md new file mode 100644 index 0000000000..a9e138cd22 --- /dev/null +++ b/src/pages/docs/octopus-ai/mcp/remote/use-cases.md @@ -0,0 +1,73 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-08-17 +modDate: 2026-08-17 +title: Octopus Remote MCP use cases +navTitle: Use cases +description: Explore how Octopus Remote MCP helps teams track releases, diagnose failures, automate deployments, audit changes, and manage tenants. +navOrder: 2 +--- + +Octopus Remote MCP lets your AI assistant work with the deployment information and operations in your Octopus instance. These use cases show how it can reduce investigation time, make release status easier to understand, and help teams act without manually piecing together information from different parts of Octopus. + +## Release visibility + +Release visibility connects a pull request (PR) or feature to its releases, deployments, environments, and tenants. This helps developers and support teams answer what shipped, where it shipped, and whether the deployment succeeded without tracing each item manually. + +Example prompts: + +- "Show me the deployment status for PR 1842 in the Payments API project. When was it deployed to the Acme tenant?" +- "When did the checkout timeout fix from PR 1842 reach Production?" +- "Which version of the Payments API is the Acme tenant running, and were there any problems with its latest deployment?" + +## Incident diagnosis + +Incident diagnosis brings together deployment and runbook task details, logs, and related Octopus resources. This gives responders a faster starting point for identifying the failed step, understanding the cause, and deciding what to investigate next. + +Example prompts: + +- "Investigate the latest failed deployment for the Payments API project and explain the likely cause." +- "Why did the Nightly database maintenance runbook fail, and which step should I investigate first?" +- "What changed in Production before the Payments API incident, when was each change deployed, and which deployment targets received it?" + +## Release progression + +Release progression covers the path from creating a release to promoting it through its lifecycle. Your assistant can explain lifecycle rules, preview a deployment before it starts, create and deploy releases, run runbooks, and generate release notes. + +Example prompts: + +- "Describe the Payments API lifecycle, including its phases and progression rules." +- "Preview release 2.4.1 of the Payments API for Test and summarize what will run." +- "Create release 2.4.1 of the Payments API and deploy it to Development." +- "Promote Payments API release 2.4.1 to the next lifecycle environment." +- "Generate release notes for release 2.4.1 and attach them to the release." +- "Run the Restart payment workers runbook in Production." + +Operations that make changes run with the permissions of the API key used to connect the assistant. Use a dedicated [Agent Service Account](/docs/security/users-and-teams/service-accounts#agent-service-accounts) and grant it only the permissions it needs. + +## Operational oversight + +Operational oversight summarizes activity across projects, tasks, deployment targets, and audit events. This helps platform teams identify unhealthy infrastructure, blocked work, and unusual changes without reviewing each project separately. + +Example prompts: + +- "Report deployment health across all projects over the last 7 days. Highlight recurring failures and the projects most affected." +- "List running, queued, and failed tasks across the instance. Group them by state and show how long they have been in that state." +- "Review deployment targets in Production and summarize their health, roles, and environments." +- "What changed in the Payments space in the last hour? Summarize the relevant audit events." + +## Tenant configuration + +Tenant configuration combines tenant details, tags, and variable status to help teams manage deployments at scale. This makes it easier to find inconsistent configuration before it causes a tenant-specific deployment failure. + +Example prompts: + +- "Find tenants in the Payments space with incomplete variable configuration and list the missing values." +- "Show me the tenant tag sets used in the Payments space and summarize how tenants are grouped." +- "Find the Acme tenant and show its connected projects, environments, tags, and configuration status." + +## Related links + +- [Octopus Remote MCP](/docs/octopus-ai/mcp/remote) +- [Agent Service Accounts](/docs/security/users-and-teams/service-accounts#agent-service-accounts) +- [Agent API keys](/docs/octopus-rest-api/how-to-create-an-api-key#creating-an-agent-api-key) diff --git a/src/pages/docs/octopus-ai/mcp/use-cases.md b/src/pages/docs/octopus-ai/mcp/use-cases.md new file mode 100644 index 0000000000..4e26e9a697 --- /dev/null +++ b/src/pages/docs/octopus-ai/mcp/use-cases.md @@ -0,0 +1,8 @@ +--- +layout: src/layouts/Redirect.astro +title: Redirect +redirect: https://octopus.com/docs/octopus-ai/mcp/local/use-cases +pubDate: 2025-04-04 +navSearch: false +navSitemap: false +--- diff --git a/src/pages/docs/octopus-ai/mcp/use-cases.mdx b/src/pages/docs/octopus-ai/mcp/use-cases.mdx deleted file mode 100644 index aa2e95dc9c..0000000000 --- a/src/pages/docs/octopus-ai/mcp/use-cases.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -layout: src/layouts/Default.astro -pubDate: 2025-04-04 -modDate: 2025-08-01 -title: Use Cases -description: -navOrder: 1 ---- - -Below are some typical example use cases that might give you a good starting point to experiment with the Octopus Deploy MCP server. - -We are eager to hear how you use it and what features you would like to see included in future versions. - -## Capability: Change Management - -Reason about what changes have been deployed where, to help you understand what your customers are using in production. - -### Production Version Tracking - -Quickly find out what version of your software a customer, represented by a Tenant, is running in Production, and identify if there were any issues with their most recent deployment. - -#### 📝 Example Prompt - -```text -Customer X have submitted a support ticket complaining that there is a bug in the latest release of App. Can you tell me what release they are on, when it was deployed, and if there were any issues with the deployment? -``` - -## Capability: Troubleshooting - -Get to the root cause of failures or unhealthy deployment targets, allowing you to more quickly recover from failures. - -### Deployment Health Analysis - -Check for failed deployments or unhealthy kubernetes workloads, analyze the failure reasons and suggest solutions. - -#### 📝 Example Prompt: Deployment Health - -```text -Check health of the {ServiceName} service in the {SpaceName} space and report any issues found, check status of kubernetes services to produce a comprehensive report -``` - -#### 💡 Tips for customizing - -- Prompt for kubernetes status to trigger kubernetes [live object status](/docs/kubernetes/live-object-status) check - -## Capability: Administration, Audit, and Compliance - -Ensure your Octopus instance is in optimal shape, and that deployments continue to execute happily and healthily. - -### Certificate Expiry Monitoring - -Identify unhealthy resources, expiring certificates or find unused projects in your Octopus instance. - -#### 📝 Example Prompt: Certificate Expiry - -```text -Find certificates soon set to expire in {SpaceName} space -``` - -### Resource Access Validation - -Find configured resources in your Octopus instance and check if they have access to the desired targets. - -#### 📝 Example Prompt: Resource Access - -```text -Check accounts configured in {SpaceName} space in my Octopus instance, find the preproduction azure account and then check which resources are available in that subscription using the azure mcp -```