Skip to main content
Version: 1.1.x

Get Started

What is MCPX?​

MCPX is the Control Plane for your agents.

It gives you a single, powerful gateway to manage how AI agents access real-world tools—securely, observably, and at scale. Whether you're prototyping with Claude or deploying to production, MCPX ensures your agents interact with tools the right way, every time.

Why MCPX?​

As agents become more capable, their access to APIs and services must be governed, secured, and monitored just like any other production system. MCPX delivers:

  • Centralized access: Aggregate and expose tool servers through a unified endpoint.
  • Policy enforcement: Control which tools and methods are accessible to which agents.
  • Full observability: Track usage, token cost, latency, and errors across all tool calls.
  • Production readiness: Container-native, CI/CD-friendly, and built for real-world deployment.

With MCPX, you can safely connect your agents to anything, without losing control.

Architecture​

MCPX is designed as a lightweight, powerful middleware layer between your client (or LLM agent) and one or more MCP-compatible tool servers. Instead of wiring agents directly to individual tool servers, MCPX exposes a single entry point that transparently handles spawning, routing, and communication with backend services.

MCPX Architecture

The key characteristics of MCPX are:

Single Entry Point
MCPX provides a unified HTTP interface using StreamableHTTP or Server-Sent Events (SSE), so your LLM or client only needs to connect to one API surface. No need to manage dozens of tool endpoints.

Subprocess Communication via stdio
Backend MCP-compatible tools are launched as subprocesses using the stdio transport defined by the Model Context Protocol (MCP). This ensures lightweight, language-agnostic execution.

Dynamic Routing & Multiplexing
MCPX dispatches tool calls to the appropriate tool based on your configuration—whether you're running one tool or many. This allows teams to scale and swap tools without changing client logic.

Policy & Access Control Ready
Route-level and tool-level access can be enforced via config-defined access policies, ensuring each agent or user only accesses what they’re allowed to.

Zero-Config for Clients
Your agent or client doesn’t need to know what tools exist or where they live—just point it at MCPX and let it handle the orchestration.

Environment Variables​

MCPX can be configured via environment variables to control logging, authentication, metrics, configuration paths, and runtime behavior. Below is a list of supported variables, their meaning, expected input, and default values.

LOG_LEVEL​

Description: Sets the logging verbosity for MCPX.
Accepted Values: error, warn, info, http, verbose, debug, silly
Default: info

AUTH_KEY​

Description: Optional shared secret used for authenticating incoming connections to MCPX. When set, all requests must include the x-lunar-auth-key header matching this value.
Accepted Values: Any string
Default: None (authentication is disabled)

PORT​

Description: Specifies the port MCPX will bind to for incoming HTTP traffic to MCPX.
Accepted Values: Any valid port number (integer)
Default: 9000

ENABLE_HUB​

Description: Controls whether MCPX should connect to a Lunar AI Gateway (for centralized coordination).
Accepted Values: true, false (as strings)
Default: true

CONTROL_PLANE_HOST​

Description: Sets the host URL of the Lunar AI Gateway MCPX should connect to.
Accepted Values: Any valid URL
Default: http://localhost:9001

ENABLE_METRICS​

Description: Controls whether metrics should be exposed (e.g. for Prometheus scraping).
Accepted Values: true, false (as strings)
Default: true

SERVE_METRICS_PORT​

Description: Defines the port on which MCPX serves its metrics endpoint.
Accepted Values: Any valid port number (integer)
Default: 3000

APP_CONFIG_PATH​

Description: Path to the YAML file containing application-level configuration (e.g., ACLs, rate limits).
Accepted Values: String path to a .yaml file
Default: config/app.yaml

SERVERS_CONFIG_PATH​

Description: Path to the JSON file that defines which MCP servers/tools should be spawned by MCPX.
Accepted Values: String path to a .json file
Default: config/mcp.json

Features at a Glance​

FeatureDescription
Access Control ListDefine global, service-level, or tool-level access per consumer group using the x-lunar-consumer-tag header.
API Key AuthenticationOptional API key auth using x-lunar-api-key, configured via the API_KEY environment variable.
Tool GroupingOrganize tools into logical groups using toolGroups for fine-grained access or routing.
Lunar Gateway IntegrationSeamlessly connect with Lunar Gateway by setting LUNAR_PROXY_HOST for downstream proxying.
Built In MetricsExposes Prometheus-compatible metrics (/metrics) including detailed tool_call_duration_ms histograms.

Get Started​