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

> Configure Docker deployment with Docker Compose for the MCP Ambari API. Deploy the stack easily by setting up your env file and running docker-compose up -d.

- Repository: [JungJungIn/mcp-ambari-api](https://github.com/call518/mcp-ambari-api)
- Tags: how-to-guide
- Published: 2026-02-26

---

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

```bash
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`](https://github.com/call518/mcp-ambari-api/blob/main/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:

```bash
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`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py) (which registers all MCP tools) or [`src/mcp_ambari_api/functions.py`](https://github.com/call518/mcp-ambari-api/blob/main/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:

```bash
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:

```bash
docker-compose ps

```

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

```bash
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`](https://github.com/call518/mcp-ambari-api/blob/main/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`:

```text
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=YOUR_LONG_RANDOM_SECRET_MINIMUM_32_CHARS

```

When enabled, all clients must include the Authorization header:

```json
{
  "Authorization": "Bearer YOUR_LONG_RANDOM_SECRET_MINIMUM_32_CHARS"
}

```

This setting is parsed by [`src/mcp_ambari_api/mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/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`](https://github.com/call518/mcp-ambari-api/blob/main/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`](https://github.com/call518/mcp-ambari-api/blob/main/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`](https://github.com/call518/mcp-ambari-api/blob/main/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`](https://github.com/call518/mcp-ambari-api/blob/main/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`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py) or [`src/mcp_ambari_api/functions.py`](https://github.com/call518/mcp-ambari-api/blob/main/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`](https://github.com/call518/mcp-ambari-api/blob/main/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.