Egorp/remote mcp

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)

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)

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)

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)