# MCP Servers

MCP servers give AI models access to new tools, data, or external systems. By adding MCP servers, Morpheus AI agents could have functionality with or visibility into cloud provider integrations (querying existing IT stacks, performing security reviews, or requesting cost breakdowns), monitoring integrations (investigating resource spikes or alerts from promethius or Grafana), change management integrations (updating Jira tickets or updating ServiceNow change requests), documentation generation, and anything else you can imagine. The Morpheus AI feature set allows users to integrate with as many MCP servers as necessary an apply some or all of them to agents. By default, a Morpheus MCP server is pre-configured to give agents visibility into the Morpheus environment and access to its powerful toolset.

Adding MCP Servers

1. Navigate to Tools > AI Services > MCP Servers
2. Click Create MCP Server
3. Configure the following:

   1. **NAME:** A name for the MCP server in Morpheus UI
   2. **PROTOCOL:** Select the transport mechanism by which the MCP server communicates with its clients (Streamable HTTP, STDIO, or SSE)
   3. **SERVICE URL:** The HTTP endpoint for Streamable HTTP or SSE protocols, or the command path for STDIO
   4. **ARGUMENTS:** (STDIO only) Optional command arguments to go with the STDIO command path
   5. **CREDENTIALS:** Select a previously stored credential or select Local Credentials to enter an API key directly into the modal
   6. **DESCRIPTION:** An optional description to describe the tools provided by the MCP server
4. Click Create MCP Server

![Creating a new MCP server](https://support.hpe.com/hpesc/public/api/document/sd00008014en_us/GUID-F7D57A54-E377-4E38-B976-79482A312DD3-high.png)

Exposing the Morpheus MCP Server to MCP-Compatible Clients

Morpheus includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes infrastructure management tools to AI assistants like GitHub Copilot CLI, Claude Desktop, OpenCode, and other MCP-compatible clients.

**Prerequisites**

- A Morpheus appliance running v8.1.1+
- An API access token or OAuth2 client credentials
- An MCP-compatible client (ex. GitHub Copilot CLI, Claude Desktop, OpenCode, etc)
- A valid SSL certificate on the Morpheus appliance (see below for more on SSL certificates)

**Generate a Morpheus API Token**

1. Log into your Morpheus appliance
2. Navigate to User Settings by clicking on the logged in user's name in the upper-right
3. Click on the API Keys tab
4. Click + ADD
5. Provide a Name for the key and select a Client ID. Additional Client IDs can be created (if needed) in global settings
6. Copy the key and save it for a later step. The key is not shown again after it is created

Morpheus API can also be used to generate an API key. See the example below and substitute relevant details for your environment:

```
```
curl -X POST "https://your-morpheus-host/oauth/token" \  
  -H "Content-Type: application/x-www-form-urlencoded" \  
  -d "grant_type=password&scope=write&client_id=morph-api&username=YOUR_USER&password=YOUR_PASS"
```
```

The response contains an `access_token` to use as your Bearer token.

**MCP Server Endpoints**

The MCP Server is available at:

| Transport | Endpoint | Method | Description |
| --- | --- | --- | --- |
| Streamable HTTP | `/api/mcp` | POST | JSON-RPC 2.0 messages |
| Streamable HTTP | `/api/mcp` | GET | SSE notification stream |
| Streamable HTTP | `/api/mcp` | DELETE | Session termination |
| Legacy SSE | `/api/mcp/sse` | GET | SSE endpoint (emits message URI) |
| Legacy SSE | `/api/mcp/messages` | POST | JSON-RPC messages (legacy) |

All endpoints require authentication via an `Authorization: Bearer <token>` header.

**Configure GitHub Copilot CLI**

Add the Morpheus MCP server to your Copilot CLI configuration file. Note that in both examples below you will need to replace the Morpheus host and API token placeholders with relevant values in your environment.

- Option A: Project-level config (recommended)

  Create or edit `.github/copilot-mcp.json` in your project root:

  ```
  ```
  {  
    "mcpServers": {  
      "morpheus": {  
        "type": "http",  
        "url": "https://your-morpheus-host/api/mcp",  
        "headers": {  
          "Authorization": "Bearer YOUR_API_TOKEN"  
        }  
      }  
    }  
  }
  ```
  ```
- Option B: User-level config

  Edit `~/.config/github-copilot/mcp.json`:

  ```
  ```
  {  
    "mcpServers": {  
      "morpheus": {  
        "type": "http",  
        "url": "https://your-morpheus-host/api/mcp",  
        "headers": {  
          "Authorization": "Bearer YOUR_API_TOKEN"  
        }  
      }  
    }  
  }
  ```
  ```

**Configure Claude Desktop**

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```
```
{  
  "mcpServers": {  
    "morpheus": {  
      "type": "http",  
      "url": "https://your-morpheus-host/api/mcp",  
      "headers": {  
        "Authorization": "Bearer YOUR_API_TOKEN"  
      }  
    }  
  }  
}
```
```

**Configure OpenCode**

- Option A: Manual config file

  Add to your `opencode.json` (or `opencode.jsonc`) configuration file:

  ```
  ```
  {  
    "mcp": {  
      "morpheus": {  
        "type": "remote",  
        "url": "https://your-morpheus-host/api/mcp",  
        "headers": {  
          "Authorization": "Bearer YOUR_API_TOKEN"  
        }  
      }  
    }  
  }
  ```
  ```

  NOTE

  OpenCode uses `"type": "remote"` for HTTP-based MCP servers (as opposed to `"type": "local"` for stdio-based servers).
- Option B: OpenCode CLI

  Use the OpenCode CLI to add the server interactively:

  ```
  ```
  opencode mcp add
  ```
  ```

  Provide:
  - **Name:**`morpheus`
  - **Type:** `remote`
  - **URL:** `https://your-morpheus-host/api/mcp`
  - **Headers:** `Authorization: Bearer YOUR_API_TOKEN`

  To verify the server was added:

  ```
  ```
  opencode mcp list
  ```
  ```

**OpenCode with Category Filtering**

```
```
{  
  "mcp": {  
    "morpheus": {  
      "type": "remote",  
      "url": "https://your-morpheus-host/api/mcp",  
      "headers": {  
        "Authorization": "Bearer YOUR_API_TOKEN",  
        "X-Mcp-Tool-Categories": "instances,clouds,servers,monitoring"  
      }  
    }  
  }  
}
```
```

**Configure Generic MCP Clients**

For any MCP client that supports Streamable HTTP transport, configure:

- **URL:**`https://your-morpheus-host/api/mcp`
- **Transport:** Streamable HTTP (POST)
- **Auth Header:** `Authorization: Bearer YOUR_API_TOKEN`
- **Content-Type:** `application/json`

For clients that only support legacy SSE transport:

- **SSE URL:**`https://your-morpheus-host/api/mcp/sse`
- **Message URL:** `https://your-morpheus-host/api/mcp/messages`

**SSL/TLS Certificates**

IMPORTANT

Most MCP clients require a valid, trusted SSL certificate on the Morpheus appliance. Self-signed or untrusted certificates will cause connection failures because MCP clients typically to not offer a way to skip certificate verification.

**Using A Trusted Certificate (Recommended)**

Use a certificate from a trusted CA (Let's Encrypt, DigiCert, etc.) on your Morpheus appliance. This works out of the box with all MCP clients.

**Self-Signed Certificates**

If your appliance uses a self-signed certificate, you must add it to your operating system's trust store so that MCP clients will accept it:

```
```
# macOS: Add to system keychain  
sudo security add-trusted-cert -d -r trustRoot \  
  -k /Library/Keychains/System.keychain /path/to/morpheus-cert.pem  
  
# Linux: Add to CA bundle  
sudo cp /path/to/morpheus-cert.pem /usr/local/share/ca-certificates/morpheus.crt  
sudo update-ca-certificates  
  
# Windows (PowerShell as Administrator)  
Import-Certificate -FilePath "C:\path\to\morpheus-cert.pem" -CertStoreLocation Cert:\LocalMachine\Root
```
```

For Node.js-based MCP clients, you can alternatively set the `NODE_EXTRA_CA_CERTS` environment variable:

```
```
export NODE_EXTRA_CA_CERTS=/path/to/morpheus-cert.pem
```
```

NOTE

The `-k` / `--insecure` flag in curl examples throughout this doc is only for manual testing. MCP clients do not support disabling certificate verification.

**Tool Category Filtering**

By default, the MCP server exposes all 1112 tools covering the full Morpheus REST API. You can optionally filter the tool list to only include specific categories, which reduces the tool count for clients that perform better with fewer tools.

Pass a comma-separated list of category names via either:

- **HTTP Header:**`X-Mcp-Tool-Categories`
- **Query Parameter:** `toolCategories`

The filter only affects tool discovery (`tools/list`). Any registered tool can still be called regardless of the filter — this prevents breaking tool chains where one tool references another.

Header Example:

```
```
{  
  "mcpServers": {  
    "morpheus": {  
      "type": "http",  
      "url": "https://your-morpheus-host/api/mcp",  
      "headers": {  
        "Authorization": "Bearer YOUR_API_TOKEN",  
        "X-Mcp-Tool-Categories": "instances,clouds,networks,monitoring"  
      }  
    }  
  }  
}
```
```

Query Parameter Example:

```
```
{  
  "mcpServers": {  
    "morpheus": {  
      "type": "http",  
      "url": "https://your-morpheus-host/api/mcp?toolCategories=instances,clouds,networks,monitoring",  
      "headers": {  
        "Authorization": "Bearer YOUR_API_TOKEN"  
      }  
    }  
  }  
}
```
```

**Available Categories**

There are 60 tool categories. Select only the categories relevant to your use case:

| Category | Tools | Description |
| --- | --- | --- |
| `networks` | 178 | Networks, subnets, routers, DNS, DHCP, IP pools, proxies, firewall rules |
| `clusters` | 115 | Kubernetes/Docker clusters, namespaces, pods, volumes, services, datastores |
| `library` | 70 | Instance type layouts, container types, option types, spec templates, file templates, scripts |
| `instances` | 61 | VM and container instances — CRUD, power actions, snapshots, cloning, resize |
| `admin` | 53 | Appliance settings, health, ping, setup, tenants, maintenance mode |
| `load-balancers` | 48 | Load balancers, virtual servers, pools, profiles, monitors |
| `monitoring` | 45 | Monitoring checks, check groups, check apps, incidents, alerts |
| `clouds` | 44 | Cloud integrations, cloud datastores, cloud folders, resource pools, security groups |
| `servers` | 33 | Bare-metal hosts, hypervisors, managed servers — CRUD and power actions |
| `provisioning` | 26 | Provision types, virtual images, pricing/service plans |
| `storage` | 24 | Storage servers, storage volumes, storage buckets, file shares |
| `deployments` | 23 | App deployments, deployment versions, deployment files |
| `backups` | 21 | Backups, backup results, backup restores, backup settings |
| `vdi` | 20 | Virtual desktop pools, VDI gateways, VDI allocations |
| `catalog` | 18 | Self-service catalog types, catalog orders, cart items, checkout, inventory |
| `apps` | 17 | Morpheus apps (multi-tier), app lifecycle, app security groups, wiki |
| `roles` | 16 | Roles and role permissions management |
| `integrations` | 16 | Third-party integrations (ITSM, IPAM, DNS, CM, etc.) |
| `groups` | 16 | Infrastructure groups, group clouds, group wiki |
| `tasks` | 14 | Automation tasks — shell scripts, HTTP, Ansible, Puppet, Chef, etc. |
| `jobs` | 14 | Scheduled jobs and job executions |
| `billing` | 14 | Billing, invoices, invoice line items |
| `archives` | 14 | Archive buckets and archive files |
| `containers` | 12 | Container/node actions — start, stop, restart, suspend, attach logs |
| `credentials` | 11 | Credential store — CRUD for stored credentials |
| `security` | 10 | Security scans and security packages |
| `user-settings` | 9 | Current user settings and preferences |
| `power-schedules` | 9 | Power schedule policies for automated start/stop |
| `options` | 9 | Options API for dynamic form lookups (network options, zone options, etc.) |
| `guidance` | 8 | Cost and resource optimization recommendations |
| `logs` | 7 | Log search and cluster log retrieval |
| `image-builds` | 7 | Image build pipelines and image build executions |
| `blueprints` | 7 | Blueprints (app templates) CRUD |
| `wiki` | 6 | Wiki pages — server, cloud, group, cluster, instance wiki |
| `user-sources` | 6 | Identity sources (LDAP, SAML, etc.) |
| `reports` | 6 | Report types, report execution and results |
| `provisioning-licenses` | 6 | Software license management and license reservations |
| `policies` | 6 | Governance policies |
| `migrations` | 6 | Hypervisor console/migration tools |
| `environments` | 6 | Environment tags (dev, staging, production, etc.) |
| `whitelabel-settings` | 5 | Appliance white-labeling / branding |
| `user-groups` | 5 | User groups management |
| `scale-thresholds` | 5 | Auto-scale threshold definitions |
| `resource-pools` | 5 | Resource pool / compute zone management |
| `prices` | 5 | Price definitions for billing |
| `price-sets` | 5 | Price set groupings |
| `preseed-scripts` | 5 | Preseed/unattend scripts for OS automation |
| `email-templates` | 5 | Email notification templates |
| `clients` | 5 | OAuth client management |
| `certificates` | 5 | SSL certificate management |
| `budgets` | 5 | Budget definitions and tracking |
| `boot-scripts` | 5 | Boot scripts for bare-metal provisioning |
| `approvals` | 5 | Approval requests and approval actions |
| `license` | 4 | Morpheus license management |
| `key-pairs` | 4 | SSH key pair management |
| `execution` | 3 | Execution request / remote command execution |
| `public-archives` | 2 | Public archive file links |
| `forgot` | 2 | Password reset / forgot password |
| `search` | 1 | Global search across all resource types |

**Common Filter Presets**

Here are some useful category combinations for different use cases:

| Use Case | Categories |
| --- | --- |
| **VM Operations** | `instances,servers,clouds,networks,monitoring` |
| **Kubernetes** | `clusters,instances,clouds,networks,storage` |
| **Service Catalog** | `catalog,provisioning,library,options` |
| **Networking** | `networks,load-balancers,security,certificates` |
| **Cost Management** | `billing,budgets,guidance,prices,price-sets` |
| **Automation** | `tasks,jobs,execution,power-schedules,scale-thresholds` |
| **Administration** | `admin,roles,user-groups,user-sources,user-settings,license` |
| **Provisioning** | `instances,clouds,library,options,provisioning,networks,groups,resource-pools` |
| **Full Operations** | `instances,servers,clouds,clusters,networks,monitoring,tasks,jobs` |

**Available Tools**

The MCP server exposes 1112 tools providing full coverage of the Morpheus REST API. All tool calls execute with the permissions of the authenticated user. Key tools include:

| Area | Example Tools |
| --- | --- |
| **Instances** | `list_instances`, `get_instance`, `create_instance`, `start_instance`, `stop_instance`, `restart_instance`, `delete_instance`, `resize_instance`, `clone_instance`, `snapshot_instance` |
| **Servers** | `list_servers`, `get_server`, `create_server`, `start_server`, `stop_server`, `delete_server` |
| **Clouds** | `list_clouds`, `get_cloud`, `create_cloud`, `refresh_cloud`, `list_cloud_datastores`, `list_cloud_resource_pools` |
| **Clusters** | `list_clusters`, `get_cluster`, `create_cluster`, `list_cluster_namespaces`, `list_cluster_pods` |
| **Networks** | `list_networks`, `get_network`, `create_network`, `list_network_pools`, `list_network_domains`, `list_network_routers` |
| **Monitoring** | `get_health`, `list_checks`, `list_alerts`, `list_incidents`, `list_check_groups` |
| **Automation** | `list_tasks`, `execute_task`, `list_workflows`, `execute_workflow`, `list_jobs` |
| **Catalog** | `list_catalog_items`, `get_catalog_item`, `create_catalog_order`, `add_catalog_cart_item`, `checkout_catalog` |
| **Admin** | `whoami`, `list_users`, `list_accounts`, `get_health`, `get_activity` |
| **Search** | `search` (global search across all resource types) |

Use `tools/list` to retrieve the full tool listing, or apply a category filter (see the filter presets table) to narrow the response.

**Verify the Connection**

Test the MCP server manually with curl:

```
```
# Initialize handshake  
curl -X POST "https://your-morpheus-host/api/mcp" \  
  -H "Authorization: Bearer YOUR_API_TOKEN" \  
  -H "Content-Type: application/json" \  
  -d '{  
    "jsonrpc": "2.0",  
    "id": 1,  
    "method": "initialize",  
    "params": {  
      "protocolVersion": "2025-06-18",  
      "clientInfo": {"name": "curl-test", "version": "1.0"}  
    }  
  }'
```
```

List all available tools:

```
```
curl -X POST "https://your-morpheus-host/api/mcp" \  
  -H "Authorization: Bearer YOUR_API_TOKEN" \  
  -H "Content-Type: application/json" \  
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'
```
```

List tools filtered to a category:

```
```
curl -X POST "https://your-morpheus-host/api/mcp?toolCategories=instances,clouds" \  
  -H "Authorization: Bearer YOUR_API_TOKEN" \  
  -H "Content-Type: application/json" \  
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'
```
```

Call a tool (whoami):

```
```
curl -X POST "https://your-morpheus-host/api/mcp" \  
  -H "Authorization: Bearer YOUR_API_TOKEN" \  
  -H "Content-Type: application/json" \  
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "whoami", "arguments": {}}}'
```
```

NOTE

These curl examples assume a trusted SSL certificate. Add `-k` only for local testing with self-signed certs — see the section above on SSL/TLS certificates.

**Example Usage in Copilot**

Once configured, you can ask Copilot to interact with your Morpheus environment. Here are some examples:

```
```
> List all running instances in my VMware cloud  
> What's the health status of the appliance?  
> Show me recent failed provisioning processes  
> Search for instances named "web-prod"  
> Execute task 42 on instance 100  
> Who am I logged in as?  
> Create a new Ubuntu instance on my VMware cloud  
> Show me all network pools  
> Order the "Dev Server" catalog item  
> List my Kubernetes cluster namespaces
```
```

**Architecture**

The MCP server acts as an API gateway, that is, tool calls are proxied to the existing Morpheus REST API internally using the caller's Bearer token. This mean:

- All existing permissions are enforced and users can only access what their Roles allow
- No new service dependencies, the MCP layer is thin and stateless
- Full API parity: Every tool maps directly to a documented REST API endpoint

```
```
MCP Client ──► /api/mcp (McpController) ──► McpService ──► /api/* (internal HTTP)  
                  │                              │  
                  │ OAuth2 Bearer Token           │ Same token forwarded  
                  │                              │  
                  ▼                              ▼  
              Auth Check                   Existing API Controllers
```
```

Tools are organized into 20 provider classes by API domain (`InstanceToolProvider`, `NetworkToolProvider`, `ClusterToolProvider`, etc.) and `McpService` aggregates them at startup into a single flat registry. The optional category filter allows consumers to control which tools are advertised during discovery without affecting tool execution.
