Morpheus MCP Server¶

Every HPE Morpheus Enterprise appliance exposes a built-in MCP (Model Context Protocol) server at /api/mcp. This endpoint allows external AI tools — such as Claude Desktop, VS Code Copilot, cursor, or custom automation scripts — to interact with Morpheus using the same tool-calling interface that powers the built-in AI chat.

The MCP server provides access to the full Morpheus API surface through categorized tools, with dynamic loading to keep initial responses lightweight. All operations respect the authenticated user’s existing RBAC permissions.

Endpoint¶

The server implements MCP protocol version 2025-06-18 with Streamable HTTP as the primary transport.

Authentication¶

External clients authenticate using the same mechanisms as the Morpheus REST API:

• Bearer Token — Authorization: Bearer <your-api-token> header (recommended)

• Access Token — ?access_token=<token> query parameter

• Execution Token — Authorization: Execution <token> header (for task/job contexts)

All tool executions enforce the authenticated user’s role permissions. A user can only access tools and resources their Morpheus role allows.

Connecting External Clients¶

Claude Desktop, Cursor, VS Code, or any MCP-compatible client:

{
  "mcpServers": {
    "morpheus": {
      "url": "https://your-morpheus-host/api/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token-here"
      }
    }
  }
}

Custom scripts (Python, Node, etc.):

Any HTTP client that supports the MCP Streamable HTTP transport can connect. Send a POST to /api/mcp with a JSON-RPC 2.0 initialize message to start a session, then use the returned Mcp-Session-Id header on subsequent requests.

Session Management¶

• Sessions are created on successful initialize handshake

• The server returns a Mcp-Session-Id response header — include this on all subsequent requests

• Sessions expire after 1 hour of inactivity

• Use DELETE /api/mcp with the session header to explicitly terminate a session

Dynamic Tool Loading¶

The MCP server uses progressive category loading to keep the initial tool list manageable for LLMs (max 120 tools per response). On first connection, clients see:

Meta-tools (always available):

• get_tool_details — Get detailed documentation for a specific tool

• search_external_tools — Discover tools from connected external MCP servers

• load_external_tools — Make discovered external tools callable in the session

• get_result_excerpt — Retrieve excerpted portions of large results

• delegate_to_specialist — Route requests to specialist tool categories

Category loader tools (one per category):

• use_instances_tools — Load VM/container instance management tools

• use_clouds_tools — Load cloud integration tools

• use_networks_tools — Load network management tools

• use_clusters_tools — Load cluster management tools

• (and so on for each category)

When an LLM calls a category loader (e.g., use_instances_tools), the tools for that category become visible in subsequent tools/list calls. The server sends a notifications/tools/list_changed notification so clients know to re-fetch the tool list.

Tool Categories¶

The following 60 tool categories are available (subject to user permissions):

Common Filter Presets¶

Use the X-Mcp-Tool-Categories header to load only the categories relevant to your use case. The following presets cover common scenarios:

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.

Session Customization Headers¶

Control tool visibility and behavior with request headers on the initialize call:

Example: Restricting to Infrastructure Tools Only¶

For a client that should only manage infrastructure:

{
  "mcpServers": {
    "morpheus-infra": {
      "url": "https://your-morpheus-host/api/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token",
        "X-Mcp-Tool-Categories": "instances,clouds,clusters,networks,storage"
      }
    }
  }
}

Example: Read-Only Monitoring Client¶

For a monitoring dashboard that should never modify resources:

{
  "mcpServers": {
    "morpheus-monitor": {
      "url": "https://your-morpheus-host/api/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token",
        "X-Mcp-Tool-Categories": "monitoring,logs,health,reports",
        "X-Mcp-Read-Only-Tools": "true"
      }
    }
  }
}

Security Considerations¶

• All tool calls execute with the authenticated user’s permissions — the MCP server cannot bypass RBAC

• Write operations in the built-in AI chat require user confirmation; external MCP clients bypass this (the client’s LLM handles confirmation)

• Use X-Mcp-Read-Only-Tools: true for untrusted or automated clients

• API tokens used for MCP should be scoped to the minimum required role

• Sessions are isolated per user — no cross-user data leakage

Exposing to External MCP Clients¶

This section provides step-by-step instructions for connecting external MCP clients to your Morpheus appliance.

Generate a Morpheus API Token¶

To authenticate external MCP clients, you need a Morpheus API token.

Via the Morpheus UI:

1. Navigate to User Settings > API Keys tab

2. Click +ADD

3. Provide a descriptive name (e.g., mcp-claude-desktop)

4. Select the appropriate Client ID

5. Click Save and copy the generated key

Via curl:

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 field that you use as your Bearer token.

Configure GitHub Copilot CLI¶

Option A: Project-level configuration

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 configuration

Create or 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 the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Configure OpenCode¶

Option A: Manual configuration

Edit opencode.json in your project root:

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

Option B: CLI

Run opencode mcp add and provide:

• Name: morpheus

• Type: remote

• URL: https://your-morpheus-host/api/mcp

• Headers: Authorization: Bearer YOUR_API_TOKEN

Configure Generic MCP Clients¶

Streamable HTTP (recommended):

Send a POST request to https://your-morpheus-host/api/mcp with:

• Header: Authorization: Bearer YOUR_API_TOKEN

• Header: Content-Type: application/json

• Body: JSON-RPC 2.0 messages

Legacy SSE transport:

For older MCP clients that require Server-Sent Events:

• SSE URL: https://your-morpheus-host/api/mcp/sse

• Message URL: https://your-morpheus-host/api/mcp/messages

Both endpoints require the Authorization: Bearer YOUR_API_TOKEN header.

SSL/TLS Certificates¶

Using a Trusted Certificate (Recommended)¶

The recommended approach is to configure your Morpheus appliance with a certificate from a trusted Certificate Authority (CA). This ensures all MCP clients can connect without additional configuration.

Self-Signed Certificates¶

If you must use a self-signed certificate, add it to your operating system’s trust store:

macOS:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain /path/to/morpheus-cert.pem

Linux:

sudo cp /path/to/morpheus-cert.pem /usr/local/share/ca-certificates/morpheus.crt
sudo update-ca-certificates

Windows (PowerShell):

Import-Certificate -FilePath "C:\path\to\morpheus-cert.pem" -CertStoreLocation Cert:\LocalMachine\Root

Node.js-based clients:

For MCP clients built on Node.js, set the following environment variable:

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

Verifying the Connection¶

Use the following curl commands to verify your MCP server is accessible and responding correctly.

Initialize a session:

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 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 by 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:

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": {}}}'

Example Usage¶

Once an MCP client is configured and connected, you can interact with Morpheus using natural language. Example prompts:

• “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”

Architecture¶

The MCP server acts as an API gateway — tool calls are proxied to the existing Morpheus REST API internally using the caller’s Bearer token. This means:

• All existing permissions are enforced — the MCP layer does not grant any additional access beyond what the user’s role allows

• No new service dependencies — the MCP layer is thin and stateless, running within the Morpheus appliance itself

• Full API parity — every tool maps to a documented REST API endpoint, ensuring consistent behavior between MCP tool calls and direct API usage