How to Centralize 20+ MCP Servers with Lunar MCPX

TL;DR Lunar MCPX is an open-source MCP gateway from Lunar.dev. It sits between AI agents and MCP servers, aggregates them through one endpoint, enforces tool-level access controls, and logs every call

What Is Lunar MCPX

An engineer connects Claude Code to a single endpoint at localhost:9000. Twenty-six MCP servers become available instantly: database schemas, GitHub issue boards, Slack channel lists, Google Maps geocoding, and time zone resolution through a time server.

Claude Code call mcp via gateway

This is the problem Lunar MCPX solves. Without it, each MCP server gets configured directly inside each agent's config file. A team running 10 MCP servers across 5 agent types needs 50 config entries.

I've found four things matter most:

Aggregation: one endpoint for any number of MCP servers. Agents connect to localhost:9000/mcp and see every registered server.
Access control: allow or deny tools at the server level or the individual tool level. API key authentication per agent.
Live monitoring: a web UI at port 5173 that shows active agent-to-server connections in real time. Prometheus metrics at port 3000 for dashboards.
Logging: every tool invocation gets a timestamped log entry with agent identity. Entries are immutable after writing.

Prerequisites

Docker: the MCPX gateway runs as a container. Docker Desktop or Docker Engine, any current version.
An MCP-compatible client: Claude Desktop, Claude Code, Cursor, VS Code, or any agent that speaks the MCP protocol.

Step 1: Deploy MCPX With Docker

Create a config directory and start the container:

mkdir mcpx-config && cd mcpx-config

docker run --rm --pull always --privileged \
  -v ./:/lunar/packages/mcpx-server/config \
  -p 9000:9000 \
  -p 5173:5173 \
  -p 3000:3000 \
  --name mcpx \
  us-central1-docker.pkg.dev/prj-common-442813/mcpx/mcpx:latest

Three ports are exposed:

9000: the MCP gateway endpoint. Agents connect here to discover and call tools using the standard MCP transport over HTTP.
5173: the Control Plane web UI. Open this in a browser to register servers, configure access, and view live connections.
3000: Prometheus metrics.

The --privileged flag enables Docker-in-Docker. This lets MCPX launch other MCP server containers inside itself. Without it, servers need to run externally and connect via network.

After the container starts, open http://localhost:5173 in a browser. The Control Plane shows an empty state: no servers registered, no agents connected.

Step 2: Connect Claude Code to MCPX

MCPX exposes the standard MCP protocol over HTTP. Claude Code connects to it using the built-in HTTP transport.

claude mcp add --transport http mcpx http://localhost:9000/mcp --header "x-lunar-consumer-tag: Claude Code" --scope project

This connects Claude Code to the MCPX gateway using Claude Code's built-in HTTP transport. The --header flag passes metadata identity so MCPX can tag and log requests from Claude Code specifically in the Control Plane.

Step 3: Register MCP Servers

Inside the Control Plane UI at localhost:5173:

Navigate to the Servers panel.
Click "Add Server."
Pick from the Standard MCP Catalog (pre-validated public servers like Time, Slack, GitHub, Postgres) or enter a custom server URL.
Configure required environment variables or API keys.
Save.

Use Case 1: Multi-Team Access Control

Setup: One MCPX instance. Two teams. Three MCP servers (Postgres, GitHub, Slack).

Goal: Engineering sees Postgres + GitHub. Customer Success sees Slack only. Compliance monitors everything.

In the Control Plane:

Create two Tool Groups. Name one "Engineering" and one "Customer Success."
Assign Postgres and GitHub servers to the Engineering group. Assign Slack to the Customer Success group.
Generate two API keys. Label one eng-agent and one cs-agent.
In the access control panel, pin eng-agent to the Engineering group and cs-agent to the Customer Success group.

Connect two Claude Code instances using different API keys:

# Terminal 1 — engineering agent
claude mcp add --transport http mcpx http://localhost:9000/mcp --header "x-lunar-consumer-tag: Claude Code (eng)" --header "x-lunar-api-key: eng-agent-key" --scope project

# Terminal 2 — customer success agent
claude mcp add --transport http mcpx http://localhost:9000/mcp --header "x-lunar-consumer-tag: Claude Code (cs)" --header "x-lunar-api-key: cs-agent-key" --scope project

Claude Code's built-in HTTP transport passes the API key via the x-lunar-api-key header. The engineering agent sees database schemas and GitHub issues. The customer success agent sees Slack channels and messages. Neither discovers the other team's tools.

You can refer to this official docs how to setup the Authentication - https://docs.lunar.dev/mcpx/api_key_auth

Use Case 2: Centralized Secret Management

Goal: Stop storing API keys in plaintext config files across developer machines. Manage credentials centrally through MCPX.

Servers requiring secrets: Slack (needs SLACK_BOT_TOKEN), Google Maps (needs GOOGLE_MAPS_API_KEY), GitHub (needs GITHUB_TOKEN).

In the Control Plane's Server configuration:

For the Slack server, set the environment variable SLACK_BOT_TOKEN to a reference path in HashiCorp Vault.
Repeat for Google Maps and GitHub servers.
MCPX resolves the secret from Vault at connection time. The token stays in memory only for the duration of the call. It never touches the agent's config file or the terminal session history.

An agent connecting to Slack through MCPX calls slack_list_channels and gets a response. The .mcp.json file contains zero tokens, only the MCPX endpoint URL. The check log records: "Agent eng-agent called slack_list_channels at 14:32:01 UTC."

Result: A developer joins the team, runs the MCPX container from the team's config directory, and has access to every MCP server the team uses without ever handling a production API key.

Use Case 3: Tool-Level Restrictions

Goal: Give agents access to a GitHub MCP server but block destructive operations.

The GitHub MCP server exposes roughly 40 tools. Four of them are destructive: delete_repository, update_branch_protection, remove_collaborator, delete_branch.

In the MCPX Control Plane:

Open the GitHub server's tool customization panel.
Disable delete_repository, update_branch_protection, remove_collaborator, and delete_branch.
Rewrite tool descriptions for the remaining 46 tools to improve LLM accuracy. Clearer descriptions mean more precise tool selection by the agent.
Apply the customized tool set to the Engineering tool group.
Save.

When an agent requests "clean up old repositories," Claude Code can propose cleanup via GitHub Issues but the delete_repository call is blocked at the gateway. The gateway responds with "tool not available" before the call reaches GitHub's API.

Use Case 4: Centralized Config for Ephemeral Sandboxes

Goal: Eliminate MCP reconfiguration pain when using ephemeral sandboxes like sbx.

The Pain: When you run Claude Code inside a sandbox, every session starts fresh. Without MCPX, you lose all MCP configurations when the container exits. Re-adding 5+ MCP servers manually every time you spin up a new sandbox wastes minutes and introduces configuration drift.

The Setup:

Run MCPX on your host machine (or a persistent VM) — outside the sandbox
Configure all MCP servers once in the MCPX Control Plane
When starting a sandbox, expose the host network or map the MCPX port

The Connection: From inside the sandbox, connect Claude Code to the host's MCPX:

# From inside the sandbox — connect to host's MCPX
claude mcp add --transport http mcpx http://host.docker.internal:9000/mcp --header "x-lunar-consumer-tag: Claude Code (sandbox)" --scope project

Or with direct host networking:

# If MCPX runs on a known host IP
claude mcp add --transport http mcpx http://192.168.1.100:9000/mcp --header "x-lunar-consumer-tag: Claude Code (sandbox)" --scope project

The Win: One connection command instead of reconfiguring N MCP servers. When you exit the sandbox and start a fresh one minutes later, the same command restores access to all your tools instantly. All server configs, API keys, and access controls persist in MCPX

Pro Tip: Combine this with Tool Groups in MCPX. Create a "Sandbox" tool group with read-only or limited-scope tools. When connecting from inside an ephemeral environment, use an API key restricted to that group. This adds a safety boundary: even if the sandbox is compromised, the exposed credentials only grant limited access through MCPX, not direct API access to production systems.

Next Steps

The setup above runs MCPX on a single machine. For team deployments:

Persistent storage: mount an external volume so server configurations survive container restarts. The config directory mapped in the Docker command persists configurations, but volumes are standard Docker practice for production.
Reverse proxy: place Nginx or Caddy in front of port 9000 for TLS termination and domain routing. A Let's Encrypt certificate turns the HTTP endpoint into HTTPS automatically.
Production secrets: switch from Vault dev mode to the production Vault configuration with unsealing and replication. AWS Secrets Manager works for teams already on AWS.
Service discovery: register MCPX with Consul or Kubernetes DNS so agents find the gateway by hostname instead of localhost.

For teams scaling beyond a single gateway, MCPX supports Okta and Azure AD SSO with SCIM provisioning for centralized user management. An evaluation sandbox lets operators test new MCP servers in isolation before exposing them to the team. I'd add SSO and the evaluation sandbox once you hit five-plus servers — it pays for itself in avoided mistakes.

Three things to try next:

Create two Tool Groups in MCPX: one for developers with Postgres and GitHub tools, one for support with Slack and CRM tools. Assign each to a different API key and test access from separate terminals.
Configure MCPX to resolve the Slack and GitHub MCP server credentials from HashiCorp Vault. Verify an agent can connect without the token values appearing in any config file.
Set up Prometheus to scrape MCPX metrics from port 3000 and build a Grafana dashboard showing tool call latency, error rates per server, and the top-10 most-used tools across all agents.

Ready to apply AI to your Security Engineering?

Subscribe to Secengai Newsletter for weekly actionable content on AI for security engineers.

Disclaimer

This content reflects personal views, experiments, and use cases in AI and security engineering. It does not represent any employer's positions, policies, or practices.