# How to Configure Multiple Ambari Clusters with Separate MCP Servers: A Complete Deployment Guide

> Learn to configure multiple Ambari clusters with separate MCP servers. Deploy independent server processes per cluster for seamless management. Complete deployment guide.

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

---

**To manage multiple Ambari clusters with MCP-Ambari-API, you must deploy one independent server process per cluster because connection settings are loaded as global constants at startup from environment variables.**

The `call518/mcp-ambari-api` repository provides a FastMCP-based interface for Apache Ambari, but its architecture relies on static global configuration loaded at module import time. Since the connection parameters are defined as constants in [`src/mcp_ambari_api/functions.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/functions.py), you cannot dynamically switch clusters within a single process, making separate server instances mandatory for multi-cluster environments.

## Why Separate Processes Are Required

The limitation stems from how the Python module initializes its Ambari client. In [`src/mcp_ambari_api/functions.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/functions.py) (lines 61-66), the following **global constants** are defined once when the module is imported:

```python
AMBARI_HOST = os.getenv("AMBARI_HOST", "localhost")
AMBARI_PORT = os.getenv("AMBARI_PORT", "8080")
AMBARI_USER = os.getenv("AMBARI_USER", "admin")
AMBARI_PASS = os.getenv("AMBARI_PASS", "admin")
AMBARI_CLUSTER_NAME = os.getenv("AMBARI_CLUSTER_NAME", "default_cluster")

```

These values are immediately used to construct the base URL for all API calls. Because Python modules are singletons within a process, changing these environment variables after startup has no effect on the running server. The `FastMCP` instance created in [`src/mcp_ambari_api/mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py) binds to a single cluster endpoint for its entire lifecycle, exposing one `/mcp` HTTP endpoint that forwards all tool calls to the configured Ambari instance.

## Three Methods to Deploy Multiple Servers

You need one server instance per cluster, each with unique `FASTMCP_PORT` values to avoid TCP conflicts. Here are the recommended deployment patterns:

### Multiple Processes with Environment Files

For development or bare-metal deployments, run distinct processes with separate environment configurations. Each process loads a different `.env` file pointing to a specific Ambari cluster.

**Steps:**

1. Duplicate the environment template for each cluster
2. Configure unique `AMBARI_HOST` and `AMBARI_CLUSTER_NAME` values
3. Assign distinct `FASTMCP_PORT` values (e.g., 8000, 8001)
4. Launch each server in its own shell session or background process

```bash

# Create configuration files for Cluster A and Cluster B

cp .env.example clusterA.env
cp .env.example clusterB.env

# Configure Cluster A

sed -i 's/^AMBARI_HOST=.*/AMBARI_HOST=ambari-a.example.com/' clusterA.env
sed -i 's/^AMBARI_CLUSTER_NAME=.*/AMBARI_CLUSTER_NAME=CLUSTER_A/' clusterA.env
sed -i 's/^FASTMCP_PORT=.*/FASTMCP_PORT=8000/' clusterA.env

# Configure Cluster B  

sed -i 's/^AMBARI_HOST=.*/AMBARI_HOST=ambari-b.example.com/' clusterB.env
sed -i 's/^AMBARI_CLUSTER_NAME=.*/AMBARI_CLUSTER_NAME=CLUSTER_B/' clusterB.env
sed -i 's/^FASTMCP_PORT=.*/FASTMCP_PORT=8001/' clusterB.env

# Launch Server A

source clusterA.env && PYTHONPATH=./src uv run python -m mcp_ambari_api \
    --type streamable-http --host 0.0.0.0 --port 8000 &

# Launch Server B  

source clusterB.env && PYTHONPATH=./src uv run python -m mcp_ambari_api \
    --type streamable-http --host 0.0.0.0 --port 8001 &

```

After startup, `http://localhost:8000/mcp` connects to Cluster A while `http://localhost:8001/mcp` connects to Cluster B.

### Docker Compose with Multiple Services

For containerized environments, define separate services in a single [`docker-compose.yml`](https://github.com/call518/mcp-ambari-api/blob/main/docker-compose.yml) file. Each service receives its own environment block and port mapping, providing complete isolation between cluster connections.

```yaml
version: "3.8"

services:
  mcp-ambari-production:
    image: call518/mcp-ambari-api:latest
    environment:
      - AMBARI_HOST=prod-ambari.internal.com
      - AMBARI_PORT=8080
      - AMBARI_USER=admin
      - AMBARI_PASS=secure_password
      - AMBARI_CLUSTER_NAME=PROD_CLUSTER
      - FASTMCP_TYPE=streamable-http
      - FASTMCP_HOST=0.0.0.0
      - FASTMCP_PORT=8000
    ports:
      - "18001:8000"

  mcp-ambari-staging:
    image: call518/mcp-ambari-api:latest
    environment:
      - AMBARI_HOST=staging-ambari.internal.com
      - AMBARI_PORT=8080
      - AMBARI_USER=admin
      - AMBARI_PASS=staging_pass
      - AMBARI_CLUSTER_NAME=STAGING_CLUSTER
      - FASTMCP_TYPE=streamable-http
      - FASTMCP_HOST=0.0.0.0
      - FASTMCP_PORT=8001
    ports:
      - "18002:8001"

```

Run `docker-compose up -d` to start both instances. The production cluster is available at `http://localhost:18001/mcp` and staging at `http://localhost:18002/mcp`.

### Systemd Units for Production

On Linux systems, use Systemd to manage multiple server instances as system services. Create a unit file for each cluster that sources a specific environment file before starting the process.

Create `/etc/systemd/system/mcp-ambari-prod.service`:

```ini
[Unit]
Description=MCP Ambari API for Production Cluster
After=network.target

[Service]
EnvironmentFile=/opt/mcp-ambari-api/prod.env
WorkingDirectory=/opt/mcp-ambari-api
ExecStart=/usr/bin/uv run python -m mcp_ambari_api \
    --type streamable-http --host 0.0.0.0 --port 8000
Restart=on-failure

[Install]
WantedBy=multi-user.target

```

Create a second unit file `mcp-ambari-staging.service` pointing to `staging.env` and using `--port 8001`. Then enable both services:

```bash
systemctl daemon-reload
systemctl enable --now mcp-ambari-prod.service
systemctl enable --now mcp-ambari-staging.service

```

## Configuring Authentication Per Cluster

When enabling bearer-token authentication via `REMOTE_AUTH_ENABLE=true`, each server instance can maintain its own security boundary using the `REMOTE_SECRET_KEY` variable. The token verification logic in [`src/mcp_ambari_api/mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py) (function `_build_static_token_auth`) initializes at startup using the secret key from the environment.

To maintain security isolation between clusters:

1. Set unique `REMOTE_SECRET_KEY` values in each environment file
2. Generate distinct JWT tokens for clients accessing each cluster
3. Ensure firewall rules restrict cross-cluster access if servers run on shared hosts

This prevents a token issued for your staging environment from being valid against your production Ambari cluster, even if both MCP servers run on the same physical host.

## Summary

- **One process per cluster** is mandatory because `AMBARI_HOST` and related variables are global constants set at import time in [`src/mcp_ambari_api/functions.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/functions.py)
- **Unique ports required**: Each `FASTMCP_PORT` value must differ to prevent TCP binding conflicts
- **Environment isolation**: Use separate `.env` files, Docker environment blocks, or Systemd `EnvironmentFile` directives to keep cluster credentials separated
- **No runtime switching**: The architecture does not support changing clusters without restarting the server process
- **Independent authentication**: Each server can use distinct `REMOTE_SECRET_KEY` values to maintain separate security perimeters

## Frequently Asked Questions

### Can a single MCP-Ambari-API server manage multiple Ambari clusters simultaneously?

No. The server architecture in `call518/mcp-ambari-api` loads Ambari connection parameters as module-level constants when [`src/mcp_ambari_api/functions.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/functions.py) is first imported. These values remain static for the process lifetime, binding the FastMCP server instance to exactly one Ambari cluster. You must deploy separate server processes to connect to additional clusters.

### Which environment variables must be unique for each server instance?

At minimum, each instance requires unique values for `AMBARI_HOST`, `AMBARI_CLUSTER_NAME`, and `FASTMCP_PORT`. If the Ambari clusters use different credentials, `AMBARI_USER` and `AMBARI_PASS` must also differ. When authentication is enabled, assign distinct `REMOTE_SECRET_KEY` values to prevent token crossover between environments.

### How do I prevent port conflicts when running multiple servers on the same host?

Assign sequential or otherwise unique `FASTMCP_PORT` values to each instance (for example, 8000, 8001, 8002). When using Docker, map these internal ports to distinct host ports (such as 18001, 18002) using the `ports` directive in your compose file or run command. The server will fail to start if another process is already bound to its configured port.

### Is it possible to change the target Ambari cluster without restarting the server?

No. Because the `AMBARI_HOST` and related constants are evaluated once at module import time, changing these environment variables after the server starts has no effect on active connections. To point to a different cluster, you must restart the server process with the new environment configuration loaded, or deploy a parallel server instance with the desired settings.