Lunar Gateway MCPX

https://docs.lunar.dev/mcpx
Admin
Lunar Gateway MCPX is a lightweight, centralized gateway for managing and securing local-first MCP...
Tokens:20,594
Snippets:51
Trust Score:7.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Clone Repository and Install Dependencies

Source: https://docs.lunar.dev/mcpx/get_started_locally

Clones the Lunar repository and navigates to the MCPX directory, then installs the necessary Node.js dependencies for the mcpx-server.

```shell
git clone https://github.com/TheLunarCompany/lunar.git
cd lunar/mcpx
npm install
```

--------------------------------

### MCPX Features Overview

Source: https://docs.lunar.dev/mcpx/get_started

A summary of MCPX's core features, detailing their purpose and how they contribute to managing AI agent access to tools.

```APIDOC
Feature Summary:

Access Control List:
  - Description: Define global, service-level, or tool-level access per consumer group using the `x-lunar-consumer-tag` header.
  - Related: Tool Grouping

API Key Authentication:
  - Description: Optional API key authentication using `x-lunar-api-key`, configured via the `API_KEY` environment variable.

Tool Grouping:
  - Description: Organize tools into logical groups using `toolGroups` for fine-grained access or routing.
  - Related: Access Control List

Lunar Gateway Integration:
  - Description: Seamlessly connect with Lunar Gateway by setting `LUNAR_PROXY_HOST` for downstream proxying.

Built In Metrics:
  - Description: Exposes Prometheus-compatible metrics (`/metrics`) including detailed `tool_call_duration_ms` histograms.
```

--------------------------------

### Demo Client Installation

Source: https://docs.lunar.dev/mcpx/connect_with_your_client

Installs the necessary dependencies for the demo client, which is provided to help users get started with MCPX. This step is required before running the demo client application.

```bash
cd demo-client
npm install
```

--------------------------------

### MCPX Centralized Configuration Example

Source: https://docs.lunar.dev/mcpx/get_started_locally

An example JSON configuration file (mcp.json) for MCPX, defining MCP servers. This example sets up a 'time' MCP server using 'uvx' command.

```json
{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    }
  }
}
```

--------------------------------

### Install Lunar MCPX with Helm

Source: https://docs.lunar.dev/mcpx/get_started_with_k8s

Installs the Lunar MCPX Helm chart into your Kubernetes cluster. This involves adding the Lunar Helm repository, updating it, and then performing the installation.

```bash
helm repo add lunar https://helm.lunar.dev
helm repo update

helm install my-mcpx lunar/lunar-mcpx
```

--------------------------------

### MCPX Control Plane Access

Source: https://docs.lunar.dev/mcpx/get_started_locally

Details on accessing the MCPX Control Plane UI after a local instance is running. It also references local installation instructions.

```APIDOC
MCPX Control Plane:
  Access URL: http://localhost:5173/
  Local Installation: Refer to /mcpx/control_plane#local-installation
  Description: Web-based interface for managing MCPX.
```

--------------------------------

### Build MCPX Dependencies

Source: https://docs.lunar.dev/mcpx/get_started_locally

Executes the build script to prepare project dependencies for the MCPX server.

```shell
npm run build:deps
```

--------------------------------

### MCPX Successful Startup Message

Source: https://docs.lunar.dev/mcpx/get_started_with_docker

This output indicates that the MCPX server has started successfully and is listening on the specified port.

```text
MCPX server started on port 9000
```

--------------------------------

### Navigate to Configuration Directory

Source: https://docs.lunar.dev/mcpx/get_started_locally

Changes the current directory to the newly created 'config' folder.

```shell
cd config
```

--------------------------------

### Run MCPX Server Locally

Source: https://docs.lunar.dev/mcpx/get_started_locally

Starts the MCPX server in development mode from the mcpx-server package directory.

```shell
cd packages/mcpx-server
npm run dev
```

--------------------------------

### Run MCPX Docker Container

Source: https://docs.lunar.dev/mcpx/get_started_with_docker

This command launches the MCPX Docker container, mounts the local configuration directory, and exposes necessary ports. Port 3000 is optional for Prometheus metrics.

```bash
docker run --rm --name mcpx -v ./:/mcpx/packages/mcpx-server/config -p 9000:9000 -p 3000:3000 us-central1-docker.pkg.dev/prj-common-442813/mcpx/mcpx:latest
```

--------------------------------

### Successful Local Server Startup Messages

Source: https://docs.lunar.dev/mcpx/get_started_locally

Output messages indicating that the MCPX server has started successfully on the default port.

```shell
Starting mcpx server... ⚡️
Server started on port 9000
```

--------------------------------

### Create MCPX Configuration Directory

Source: https://docs.lunar.dev/mcpx/get_started_locally

Creates a 'config' directory within the mcpx-server package to store configuration files.

```shell
mkdir config
```

--------------------------------

### Run Demo Client with LLM

Source: https://docs.lunar.dev/mcpx/connect_with_your_client

Starts the demo client application, which leverages LLM capabilities from Gemini or Anthropic. Users need to provide their respective API keys as environment variables before running the start command.

```bash
# For Gemini:
GEMINI_API_KEY=<your-key> npm run start:gemini

# For Claude:
ANTHROPIC_API_KEY=<your-key> npm run start:claude
```

--------------------------------

### MCPX Prompt Example

Source: https://docs.lunar.dev/mcpx/connect_with_your_client

An example prompt to test the MCPX's ability to find walking directions using Google Maps and post them to a specified Slack channel, including formatting and emoji requirements.

```shell
> Find walking directions from Union Square to Little Island, in NYC, NY, and post it to the Slack channel <available-slack-channel-name>. Format the message nicely and spaced, and add 2-3 relevant emojis.
```

--------------------------------

### Install MCPX Control Plane Locally (npm)

Source: https://docs.lunar.dev/mcpx/control_plane

Instructions for installing the MCPX Control Plane locally. This process involves installing dependencies and starting the webserver and UI components using npm scripts. Ensure you have cloned the Lunar.dev MCPX Repo and navigated to the `/mcpx` directory.

```npm
npm run build:deps && npm install
```

```npm
npm run start:webserver
```

```npm
npm run start:ui
```

--------------------------------

### MCPX Configuration File (mcp.json)

Source: https://docs.lunar.dev/mcpx/get_started_with_docker

This JSON file is used for centralized configuration management of MCP servers within MCPX. It defines MCP servers, their commands, and arguments.

```json
{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    }
  }
}
```

--------------------------------

### MCPX Metrics Endpoint

Source: https://docs.lunar.dev/mcpx/get_started_locally

Information about the Prometheus metrics endpoint for MCPX, which is automatically exposed on port 3000.

```APIDOC
MCPX Metrics:
  Endpoint: http://localhost:3000/
  Description: Exposes Prometheus metrics for scraping.
  Port: 3000 (default)
```

--------------------------------

### Override MCPX Configuration with YAML

Source: https://docs.lunar.dev/mcpx/get_started_with_k8s

Demonstrates how to override default Lunar MCPX configurations using a local YAML file. This allows customization of settings like authentication and permissions.

```yaml
config:
  appYaml: |
    auth:
      enabled: false
    permissions:
      base: "block"
```

--------------------------------

### Launching MCP Servers with npx

Source: https://docs.lunar.dev/mcpx/target_mcp_servers

Examples of how to launch MCP servers using Node Package Manager's 'npx' command, often used for executing packages from npm. This is relevant for JavaScript-based MCP servers.

```javascript
npx -y @modelcontextprotocol/server-google-maps
```

```javascript
npx -y @modelcontextprotocol/server-slack
```

--------------------------------

### Reference Kubernetes Secrets for MCPX

Source: https://docs.lunar.dev/mcpx/get_started_with_k8s

Shows how to configure Lunar MCPX to use existing Kubernetes secrets for sensitive information, such as API keys. MCPX will inject these as environment variables.

```yaml
secretRef:
  name: my-mcpx-secret
  keys:
    - API_KEY                 # Used when `auth.enabled` is set to true
    - SOME_3RD_PARTY_API_KEY  # Any secret required by a target MCP server as env var
```

--------------------------------

### MCPX Docker Advanced Privileges

Source: https://docs.lunar.dev/mcpx/get_started_with_docker

Explains the use of elevated privileges for advanced container features like Docker-in-Docker (DinD) or network manipulation. It details the `--privileged` flag and `--cap-add=NET_ADMIN` for specific capabilities.

```markdown
To enable advanced container features, such as running Docker inside a container (Docker-in-Docker) or managing `iptables` rules, your container must be granted elevated privileges.

* Use `--privileged` when running Docker inside a container (DinD).
* Use `--cap-add=NET_ADMIN` to manipulate network settings like `iptables`.

These flags grant additional Linux capabilities to the container:

`--privileged` gives the container full access to host devices and all capabilities. This is required for DinD since it needs access to low-level kernel features.

`--cap-add=NET_ADMIN` is more restrictive and grants only the ability to configure networking, for example, to add firewall rules using iptables.

Always prefer fine-grained access like `--cap-add=NET_ADMIN` over `--privileged` unless absolutely necessary, as the latter significantly broadens the container’s access to the host.
```

--------------------------------

### Kubernetes Pod Security Context for Docker-in-Docker (DinD)

Source: https://docs.lunar.dev/mcpx/get_started_with_k8s

Configures Kubernetes Pods to enable Docker-in-Docker (DinD) by setting the `privileged` security context to `true`. This grants the container full access to host devices and kernel features required for DinD operations.

```YAML
apiVersion: apps/v1
kind: Prod
metadata:
  name: lunar-mcpx
spec:
    spec:
      containers:
        - name: mcpx
          image: us-central1-docker.pkg.dev/prj-common-442813/mcpx/mcpx:latest
          securityContext:
            privileged: true

```

--------------------------------

### Install MCPX Control Plane via Docker

Source: https://docs.lunar.dev/mcpx/control_plane

Instructions for installing the MCPX Control Plane using Docker. This command launches a containerized MCPX instance, mapping local configuration and exposing necessary ports for the UI. After running the command, access the control plane via http://localhost:5173/.

```docker
docker run --rm --name mcpx-ui -v ./config:/config -p 9001:9001 -p 5173:5173 us-central1-docker.pkg.dev/prj-common-442813/mcpx/mcpx-ui:latest
```

--------------------------------

### Kubernetes Pod Security Context for Network Admin (iptables)

Source: https://docs.lunar.dev/mcpx/get_started_with_k8s

Configures Kubernetes Pods to manipulate network settings like `iptables` by adding the `NET_ADMIN` capability. This is a more granular permission than `privileged`, allowing specific network operations without granting full host access.

```YAML
apiVersion: apps/v1
kind: Prod
metadata:
  name: lunar-mcpx
spec:
    spec:
      containers:
        - name: mcpx
          image: us-central1-docker.pkg.dev/prj-common-442813/mcpx/mcpx:latest
          securityContext:
            capabilities:
              add: ["NET_ADMIN"]

```

--------------------------------

### Parameter Overriding Example

Source: https://docs.lunar.dev/mcpx/tool_customization

Demonstrates how parameter descriptions are automatically annotated when a parameter is fixed to a constant value using overrideParams. This helps LLMs understand that the parameter is hardcoded and should not be provided by the user.

```APIDOC
Parameter Description Annotation:
  Original description for `timezone`.
  Note: This parameter is ignored – it is hardcoded to be `Europe/Paris`. Pass an empty string for this parameter. This helps LLMs understand that this parameter does not need to be provided.
```

--------------------------------

### Configure Claude Desktop for MCPX Connection

Source: https://docs.lunar.dev/mcpx/connect_with_claude

This JSON configuration is used within Claude Desktop's settings to define how it connects to MCPX. It specifies the command to execute (`npx mcp-remote`) and the arguments required, including the server endpoint and authentication headers like consumer tags and API keys. Ensure the arguments are tailored to your specific Lunar.dev setup.

```json
{
  "mcpServers": {
    "mcpx": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:9000/sse",
        "--header",
        "x-lunar-consumer-tag: developers",
        "--header",
        "x-lunar-api-key: abc123"
      ]
    }
  }
}
```

--------------------------------

### MCP Server Support Notes

Source: https://docs.lunar.dev/mcpx/target_mcp_servers

Information regarding the current support status for different types of MCP servers within MCPX. This includes notes on supported runtimes and future expansion plans.

```text
Currently, JavaScript (Node.js), Python, and Docker-based MCP servers are supported. Broader support will be added as this project evolves.
```

--------------------------------

### MCPX Server Configuration (mcp.json)

Source: https://docs.lunar.dev/mcpx/target_mcp_servers

This JSON configuration file specifies the target MCP servers that MCPX should load. Each server entry includes the command and arguments to launch the server, and optionally environment variables.

```json
{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-google-maps"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_TEAM_ID": "<your-slack-team-id>",
        "SLACK_CHANNEL_IDS": "<relevant-slack-channel-ids>"
      }
    },
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
    }
  }
}
```

--------------------------------

### MCPX Environment Variables

Source: https://docs.lunar.dev/mcpx/connect_with_your_client

Required environment variables for setting up and running MCPX. These variables configure access to external services like Slack and Google Maps.

```shell
export SLACK_BOT_TOKEN="your_slack_bot_token"
export GOOGLE_MAPS_API_KEY="your_google_maps_api_key"
export SLACK_CHANNEL_IDS="channel_id_1,channel_id_2"
export SLACK_TEAM_ID="your_slack_team_id"
export GEMINI_API_KEY="your_gemini_api_key"
```

--------------------------------

### Initialize MCP Client

Source: https://docs.lunar.dev/mcpx/connect_with_your_client

Initializes an MCP client with a name and version, then connects it using a specified transport mechanism. This is the fundamental step for client-server communication with MCPX.

```javascript
const client = new Client({ name: "mcpx-client", version: "1.0.0" });
await client.connect(transport);
```

--------------------------------

### Project Configuration Structure

Source: https://docs.lunar.dev/mcpx/app

Defines the schema for project configuration, including access permissions for consumers, tool group definitions, authentication settings, and tool extension configurations. It specifies required and optional fields for each section.

```yaml
permissions:
  base: # required. value can be "allow" or "block"
  consumers:
    developers:
      base: # required. value can be "allow" or "block"
      profiles: #optional, gets an object
        allow: #optional. expects a list of strings of profiles that are allowed
          - profile1 # example. This needs to correspond to tool group name
          - profile2
        block: #optional. expects a list of strings of profiles that are blocked
          - profile3
    my-consumer-tag:
      base: # required. value can be "allow" or "block"
      profiles: #optional. gets an object
        allow: # optional. expects a list of strings of profiles that are allowed
          - profile2
        block: # optional. expects a list of strings of profiles that are blocked
          - profile3
toolGroups:
  - name: profile1 # name of the tool group that corresponds to a profile in permissions
    services:
      serviceName1: # name of the service. This is dynamic and created by the user.
        - myTool1
        - myTool2
      serviceName2: "*" # the user can use a * to signify all the tools in one service
auth:
  enabled: # required. boolean "true" or "false"
  header: # optional string. This corresponds to the header from where to get the auth key.
toolExtensions:
  services:
    serviceName: #name of the service (dynamic, can be what the user chooses)
    serviceName2:
      childTools:
        - name: childToolName
          description: #optional
            action: # "append" or "rewrite"
            text: "description of child tool"
          overrideParams: #record tin which each value is a string, a number, or a boolean
            my-param1: 8
            my-param2: "string"
            my-param3: true

```

--------------------------------

### MCPX Configuration for Slack Integration

Source: https://docs.lunar.dev/mcpx/connect_with_your_client

Instructions on how to configure MCPX to enable Slack integration by modifying its configuration files. This step is crucial for sending results to Slack channels.

```json
{
  "tools": {
    "google_maps": {
      "enabled": true
    },
    "slack": {
      "enabled": true
    }
  }
}
```

--------------------------------

### Using mcp-remote for Server Connections

Source: https://docs.lunar.dev/mcpx/target_mcp_servers

Demonstrates how to use the 'mcp-remote' tool to connect to an MCP server exposed via SSE (Server-Sent Events). This is useful for connecting to external MCP servers or services.

```javascript
npx -y mcp-remote https://mcp.linear.app/sse
```

--------------------------------

### Configure LUNAR_GATEWAY_URL

Source: https://docs.lunar.dev/mcpx/lunar_gateway_integration

This snippet shows the environment variable configuration required for MCPX to connect to the Lunar Gateway. Ensure this variable points to your running Lunar Gateway instance.

```environment
LUNAR_GATEWAY_URL=http://localhost:8000

```

--------------------------------

### Configure API Key Auth in app.yaml

Source: https://docs.lunar.dev/mcpx/api_key_auth

Enables basic API key authentication for new connections to MCPX. Requires adding the 'auth' section to 'config.app.yaml' to activate the feature.

```yaml
auth:
  enabled: true
```

--------------------------------

### Configure MCPX Connection in Cursor

Source: https://docs.lunar.dev/mcpx/connect_with_cursor

This JSON configuration is used within Cursor's IDE settings to establish a connection to the MCPX service. It specifies the command to run, arguments including the MCPX server endpoint, and necessary headers like consumer tags and API keys.

```JSON
{
  "mcpServers": {
    "mcpx": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:9000/sse",
        "--header",
        "x-lunar-consumer-tag: cursor",
        "--header",
        "x-lunar-api-key: <YOUR_API_KEY>"
      ]
    }
  }
}
```

--------------------------------

### MCPX Configuration Files

Source: https://docs.lunar.dev/mcpx/features

Lunar MCPX utilizes configuration files for defining its behavior. Key files include app.yaml for application settings and mcp.json for specifying target MCP servers. Environment variables can override default file paths.

```APIDOC
Configuration Files:

- app.yaml: Main application configuration.
- mcp.json: Lists desired target MCP servers. Overridable by SERVERSCONFIGPATH environment variable.

Environment Variables:

- SERVERSCONFIGPATH: Overrides the default path for the mcp.json server configuration file.
```
Tokens:
Raw