How to Configure Docker Deployment with Docker-Compose for the MCP Ambari API

Deploy the MCP Ambari API stack using Docker Compose by configuring a .env file from the provided template and running docker-compose up -d to start the OpenWebUI, MCP server, and MCPO proxy containers.

The call518/mcp-ambari-api repository provides a containerized solution for integrating Ambari cluster management with LLM interfaces through the Model Context Protocol (MCP). This guide explains how to configure Docker deployment with Docker-Compose to run the complete three-service stack, enabling chat-based interaction with your Ambari clusters via a web interface.

Prepare the Environment Configuration

All runtime configuration for the Docker deployment with Docker-Compose is centralized in a single .env file. Copy the template and customize it for your Ambari cluster:

cp .env.example .env

Edit the resulting .env file to specify your Ambari connection details and port mappings. The critical variables include:

• AMBARI_HOST – Typically host.docker.internal if Ambari runs on the Docker host, or the specific hostname/IP of your Ambari server
• AMBARI_PORT – Default is 8080
• AMBARI_USER and AMBARI_PASS – Administrator credentials for Ambari
• AMBARI_CLUSTER_NAME – The name of your managed cluster (e.g., TEST-AMBARI)
• DOCKER_EXTERNAL_PORT_OPENWEBUI – Host port for the web interface (default 3001)
• DOCKER_EXTERNAL_PORT_MCP_SERVER – Host port for the MCP endpoint (default 18001)
• DOCKER_EXTERNAL_PORT_MCPO_PROXY – Host port for the OpenAPI proxy (default 8001)

The file also configures the MCP transport settings via FASTMCP_TYPE=streamable-http and FASTMCP_PORT=8000, which the mcp-server container uses internally.

Inspect the Docker Compose Architecture

The docker-compose.yml file in the repository root defines three interconnected services that share the same environment file:

open‑webui (Front-end UI)

• Image: ghcr.io/open-webui/open-webui:0.7.2
• Purpose: Provides the chat interface for LLM interaction
• Port mapping: ${DOCKER_EXTERNAL_PORT_OPENWEBUI}:8080 (default exposes 3001 on the host)

mcp‑server (Core MCP Server)

• Image: call518/mcp-server-ambari-api:1.0.1
• Role: Implements the MCP protocol and translates requests to Ambari REST API calls
• Port mapping: ${DOCKER_EXTERNAL_PORT_MCP_SERVER}:8000 (default exposes 18001)
• Volumes: Mounts ./src:/app/src/ and script directories to enable live code editing without rebuilding the image
• Healthcheck: Includes a TCP health check to ensure the HTTP endpoint is ready before dependent services start

mcpo‑proxy (MCPO Proxy)

• Image: call518/mcpo-proxy-ambari-api:1.0.3
• Function: Translates MCP calls to OpenAPI/REST for the UI
• Port mapping: ${DOCKER_EXTERNAL_PORT_MCPO_PROXY}:8000 (default exposes 8001)
• Dependency: Waits for mcp-server to report healthy before starting
• Configuration: Uses mcp-config.json.http mounted from the host

All services include extra_hosts entries to ensure host.docker.internal resolves correctly when accessing Ambari running on the Docker host.

Build or Pull Container Images

The project provides pre-built images on Docker Hub and GitHub Container Registry. You can pull them directly rather than building from source:

docker pull call518/mcp-server-ambari-api:1.0.1
docker pull call518/mcpo-proxy-ambari-api:1.0.3

Alternatively, build locally using the provided Dockerfiles:

• Dockerfile.MCP-Server – Builds a Rocky Linux-based image with Python 3.12, uv, fastmcp, and aiohttp
• Dockerfile.MCPO-Proxy – Constructs the proxy container that exposes the OpenAPI documentation endpoint

Building is only necessary if you modify the source code in src/mcp_ambari_api/mcp_main.py (which registers all MCP tools) or src/mcp_ambari_api/functions.py (which contains Ambari REST helper functions).

Launch the Stack

From the repository root directory containing your configured .env file:

docker-compose up -d

This command starts the containers in the correct dependency order:

1. open‑webui initializes and binds to http://localhost:3001
2. mcp‑server starts and exposes the MCP endpoint at http://localhost:18001/mcp
3. mcpo‑proxy starts after the server passes health checks, serving OpenAPI docs at http://localhost:8001/mcp-ambari-api/docs

Verify the deployment status:

docker-compose ps

The mcp-server container should display (healthy) in the status column. Monitor logs for troubleshooting:

docker-compose logs -f mcp-server
docker-compose logs -f mcpo-proxy

Register the MCP Tool in OpenWebUI

Once the containers are running, connect OpenWebUI to the MCP server:

1. Navigate to Settings → Tools in the OpenWebUI interface at http://localhost:3001

2. Add a new tool with the URL:

   
   http://host.docker.internal:18001/mcp
   

   (Use the value from DOCKER_EXTERNAL_PORT_MCP_SERVER if you changed the default)

3. Set the transport type to streamable-http

If you enabled authentication (see next section), provide the Bearer token in the headers configuration.

Test the integration by asking the chat interface to list cluster services; the request flows through OpenWebUI → MCPO Proxy → MCP Server → Ambari REST API, returning results via src/mcp_ambari_api/functions.py execution.

Enable Production Authentication

For production Docker deployment with Docker-Compose, secure the streamable-http endpoint by enabling token authentication in .env:

REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=YOUR_LONG_RANDOM_SECRET_MINIMUM_32_CHARS

When enabled, all clients must include the Authorization header:

{
  "Authorization": "Bearer YOUR_LONG_RANDOM_SECRET_MINIMUM_32_CHARS"
}

This setting is parsed by src/mcp_ambari_api/mcp_main.py and enforced on all incoming MCP requests. Disable authentication (REMOTE_AUTH_ENABLE=false) only for local development.

Summary

• Three-container architecture: OpenWebUI (port 3001), MCP Server (port 18001), and MCPO Proxy (port 8001) defined in docker-compose.yml
• Centralized configuration: All services read from a single .env file based on .env.example
• Live development: Volume mounts in docker-compose.yml allow editing src/mcp_ambari_api/ code without rebuilding images
• Health-check orchestration: The MCP server must pass health checks before the proxy starts, ensuring reliable startup order
• Production security: Enable REMOTE_AUTH_ENABLE and set a strong REMOTE_SECRET_KEY to protect the MCP endpoint in production environments

Frequently Asked Questions

What are the default ports used in the Docker Compose deployment?

The default ports are 3001 for the OpenWebUI interface, 18001 for the MCP server endpoint, and 8001 for the MCPO proxy. These map to internal container ports 8080 and 8000 respectively, configured through environment variables DOCKER_EXTERNAL_PORT_OPENWEBUI, DOCKER_EXTERNAL_PORT_MCP_SERVER, and DOCKER_EXTERNAL_PORT_MCPO_PROXY in your .env file.

How do I connect to an Ambari instance not running on the Docker host?

Set AMBARI_HOST in your .env file to the specific IP address or hostname of your Ambari server instead of host.docker.internal. Ensure the container can reach this address by modifying the extra_hosts section in docker-compose.yml if necessary, or ensure the target host is routable from within the Docker network.

Can I modify the MCP server code without rebuilding the Docker image?

Yes. The docker-compose.yml mounts the local ./src directory to /app/src/ inside the mcp-server container. Changes to src/mcp_ambari_api/mcp_main.py or src/mcp_ambari_api/functions.py take effect immediately by restarting the container with docker-compose restart mcp-server, requiring no image rebuild during development.

Where is the Bearer token authentication enforced in the codebase?

The authentication logic resides in src/mcp_ambari_api/mcp_main.py, which reads the REMOTE_AUTH_ENABLE and REMOTE_SECRET_KEY environment variables. When enabled, the server validates the Authorization: Bearer header on all incoming requests to the streamable-http endpoint before processing MCP tool calls.

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