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

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, 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 (lines 61-66), the following global constants are defined once when the module is imported:

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

# 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 file. Each service receives its own environment block and port mapping, providing complete isolation between cluster connections.

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:

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

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 (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
• 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 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.

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