How to Integrate MCP-OpenStack-Ops with Claude Desktop's Streamable-HTTP Interface for Advanced Workflows

To integrate MCP-OpenStack-Ops with Claude Desktop's streamable-http interface, launch the server with the --type streamable-http flag, configure the Claude Desktop JSON settings to point to the HTTP endpoint, and ensure your OpenStack credentials are set via environment variables.

The MCP-OpenStack-Ops repository (call518/mcp-openstack-ops) exposes OpenStack operations as Model Context Protocol (MCP) tools, enabling AI agents to manage cloud infrastructure through natural language. By configuring the streamable-http transport, you enable Claude Desktop to communicate with your OpenStack environment over HTTP rather than the default stdio transport, facilitating advanced workflows that require persistent connections or remote accessibility.

Architectural Overview

Understanding how the components interact ensures a reliable integration:

Component	Role	Interaction
MCP-OpenStack-Ops server (src/mcp_openstack_ops/__main__.py)	Exposes OpenStack tools as MCP functions.	Starts in either stdio (default) or streamable-http mode (--type streamable-http).
FastMCP transport layer (FASTMCP_TYPE env var)	Handles request/response framing.	In streamable-http mode it runs an HTTP server (/run endpoint) that receives JSON-encoded MCP calls and streams back responses.
Claude Desktop	UI/agent that can launch external services and call them via the configured mcpServers block.	Reads a JSON configuration that tells it how to start the MCP server, which env-vars to inject, and which transport to use.
OpenStack SDK (openstacksdk)	Low-level API client used by the tool implementations (src/mcp_openstack_ops/functions.py).	All MCP tools delegate to this SDK; the SDK uses the credentials supplied in the .env file.

The integration works by launching the MCP server in streamable-http mode, exposing a local HTTP endpoint (default 127.0.0.1:8080). Claude Desktop then sends MCP-formatted JSON payloads to that endpoint, receives streamed results, and presents them in the chat UI.

Step-by-Step Integration Guide

Clone and Install the Repository

Begin by obtaining the source code and installing dependencies:

git clone https://github.com/call518/mcp-openstack-ops.git
cd mcp-openstack-ops
uv sync                # installs dependencies defined in pyproject.toml

The uv sync command ensures all required packages—including fastmcp and openstacksdk—are available in your environment.

Configure OpenStack Credentials

Create a project-scoped .env file by copying the example:

cp .env.example .env

# Edit .env with your OpenStack credentials

The required variables include authentication endpoints, project scope, and user credentials. These values populate the openstacksdk connection object used by all MCP tools.

Launch the Streamable-HTTP Server

Start the MCP server explicitly in HTTP mode:

python -m mcp_openstack_ops --type streamable-http --host 127.0.0.1 --port 8080

Alternatively, set the environment variable FASTMCP_TYPE=streamable-http to achieve the same effect. The server exposes the /run endpoint at http://127.0.0.1:8080/run, which accepts JSON-encoded MCP requests.

For enhanced security, enable bearer-token authentication by setting MCP_AUTH_TOKEN in your environment (see the repository README for details).

Configure Claude Desktop Integration

Create or edit ~/.config/claude-desktop/mcp_servers.json and add the following server definition:

{
  "mcpServers": {
    "mcp-openstack-ops": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-openstack-ops"],
      "env": {
        "OS_AUTH_HOST": "your-openstack-host",
        "OS_AUTH_PORT": "5000",
        "OS_PROJECT_NAME": "your-project",
        "OS_USERNAME": "your-username",
        "OS_PASSWORD": "your-password",
        "OS_USER_DOMAIN_NAME": "Default",
        "OS_PROJECT_DOMAIN_NAME": "Default",
        "OS_REGION_NAME": "RegionOne",
        "OS_IDENTITY_API_VERSION": "3",
        "OS_INTERFACE": "internal",
        "OS_COMPUTE_PORT": "8774",
        "OS_NETWORK_PORT": "9696",
        "OS_VOLUME_PORT": "8776",
        "OS_IMAGE_PORT": "9292",
        "OS_PLACEMENT_PORT": "8780",
        "OS_HEAT_STACK_PORT": "8004",
        "OS_HEAT_STACK_CFN_PORT": "18888",
        "ALLOW_MODIFY_OPERATIONS": "false",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

This configuration instructs Claude Desktop to launch the MCP server using uvx, inject the necessary OpenStack credentials via environment variables, and communicate over the streamable-http transport.

Verify the Connection

Open Claude Desktop and navigate to Settings → MCP Servers. Confirm that mcp-openstack-ops appears with a "Running" status.

Test the integration by asking Claude a natural language query:

List all running instances in the current project

Claude will translate this into an MCP tool call (e.g., get_instance(status="ACTIVE", limit=10)) and send it to the HTTP endpoint. The streamed response will display the instance details in the chat interface.

Code Examples and Configuration Files

Environment Configuration (.env)

A minimal .env file for streamable-http operation:

OS_AUTH_HOST=openstack.example.com
OS_AUTH_PORT=5000
OS_AUTH_PROTOCOL=https
OS_USERNAME=admin
OS_PASSWORD=SuperSecretPassword
OS_PROJECT_NAME=myproject
OS_USER_DOMAIN_NAME=Default
OS_PROJECT_DOMAIN_NAME=Default
OS_REGION_NAME=RegionOne
ALLOW_MODIFY_OPERATIONS=false
FASTMCP_TYPE=streamable-http
MCP_LOG_LEVEL=INFO

Setting FASTMCP_TYPE=streamable-http ensures the transport layer initializes the HTTP server without requiring the --type CLI flag.

Claude Desktop Server JSON

The complete server definition for Claude Desktop's configuration:

{
  "mcpServers": {
    "mcp-openstack-ops": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-openstack-ops"],
      "env": {
        "OS_AUTH_HOST": "openstack.example.com",
        "OS_AUTH_PORT": "5000",
        "OS_PROJECT_NAME": "myproject",
        "OS_USERNAME": "admin",
        "OS_PASSWORD": "SuperSecretPassword",
        "OS_USER_DOMAIN_NAME": "Default",
        "OS_PROJECT_DOMAIN_NAME": "Default",
        "OS_REGION_NAME": "RegionOne",
        "OS_IDENTITY_API_VERSION": "3",
        "OS_INTERFACE": "internal",
        "ALLOW_MODIFY_OPERATIONS": "false",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Manual HTTP Testing with cURL

Verify the endpoint independently of Claude Desktop:

curl -X POST http://127.0.0.1:8080/run \
     -H "Content-Type: application/json" \
     -d '{
           "name": "get_instance",
           "args": {"status": "ACTIVE", "limit": 5}
         }'

The server responds with a streamed JSON object containing the tool output:

{
  "result": [
    {"id": "1234", "name": "web-01", "status": "ACTIVE"},
    {"id": "5678", "name": "db-01",  "status": "ACTIVE"}
  ],
  "metadata": {"count": 2, "query_time": "0.12s"}
}

Python Client Example

For custom tooling that interacts with the HTTP endpoint:

import requests
import json

payload = {
    "name": "get_quota",
    "args": {}
}

resp = requests.post(
    "http://127.0.0.1:8080/run",
    headers={"Content-Type": "application/json"},
    data=json.dumps(payload),
    stream=True
)

for line in resp.iter_lines():
    if line:
        print(json.loads(line))

Key Source Files and Implementation Details

File	Purpose	Link
src/mcp_openstack_ops/__main__.py	Entry point; parses CLI flags, selects transport (stdio vs streamable-http).	GitHub
src/mcp_openstack_ops/mcp_main.py	Registers all MCP tools (read-only & mutating).	GitHub
src/mcp_openstack_ops/functions.py	Helper utilities; builds the OpenStack SDK connection (get_openstack_connection).	GitHub
src/mcp_openstack_ops/connection.py	Caches and validates the OpenStack connection object.	GitHub
README.md	Comprehensive setup, transport, and Claude Desktop integration instructions.	GitHub
pyproject.toml	Declares dependencies (fastmcp, openstacksdk, etc.) that enable the streamable-http transport.	GitHub

Summary

• MCP-OpenStack-Ops exposes OpenStack operations via the Model Context Protocol, allowing Claude Desktop to manage cloud resources through natural language.
• To enable streamable-http mode, start the server with --type streamable-http or set FASTMCP_TYPE=streamable-http, which exposes a local HTTP endpoint at 127.0.0.1:8080/run.
• Claude Desktop integration requires configuring the mcpServers JSON block with the uvx command, appropriate Python version, and all OpenStack environment variables.
• The transport layer in src/mcp_openstack_ops/__main__.py handles the protocol selection, while src/mcp_openstack_ops/functions.py manages the OpenStack SDK connection.
• For production use, enable bearer-token authentication via MCP_AUTH_TOKEN and restrict modify operations using ALLOW_MODIFY_OPERATIONS=false.

Frequently Asked Questions

What is the difference between stdio and streamable-http transport in MCP-OpenStack-Ops?

The stdio transport (default) communicates via standard input/output streams, suitable for local process spawning where Claude Desktop directly manages the server lifecycle. The streamable-http transport launches an HTTP server (default 127.0.0.1:8080) that accepts JSON-encoded MCP requests at the /run endpoint and streams responses back, enabling remote access, persistent connections, and easier debugging. You select the mode via the --type CLI flag or the FASTMCP_TYPE environment variable in src/mcp_openstack_ops/__main__.py.

How do I secure the streamable-http endpoint when integrating with Claude Desktop?

To secure the HTTP transport, set the MCP_AUTH_TOKEN environment variable when starting the server. This enables bearer-token authentication, requiring all requests to include an Authorization: Bearer <token> header. Additionally, bind the server to localhost (--host 127.0.0.1) to prevent external network access, and use ALLOW_MODIFY_OPERATIONS=false to restrict destructive OpenStack operations. For production deployments, place the server behind a reverse proxy with TLS termination.

Can I run MCP-OpenStack-Ops in streamable-http mode without Claude Desktop?

Yes, the streamable-http transport operates independently of Claude Desktop. Any HTTP client can interact with the server by POSTing JSON payloads to http://127.0.0.1:8080/run. The request body must include name (the tool name) and args (a dictionary of parameters). The server returns a streamed JSON response containing the result. This allows integration with custom Python scripts, curl commands, or other AI agents that support HTTP-based MCP transports.

What environment variables are required for the OpenStack connection?

The server requires standard OpenStack authentication variables: OS_AUTH_HOST, OS_AUTH_PORT, OS_AUTH_PROTOCOL, OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME, OS_USER_DOMAIN_NAME, OS_PROJECT_DOMAIN_NAME, and OS_REGION_NAME. Service-specific ports like OS_COMPUTE_PORT (8774), OS_NETWORK_PORT (9696), and OS_VOLUME_PORT (8776) customize endpoint URLs. The ALLOW_MODIFY_OPERATIONS boolean controls whether mutating operations are exposed, and MCP_LOG_LEVEL adjusts verbosity.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}