Skip to main content
Feedback

Quick start guide

Before You Start

Make sure Docker is installed and running on your machine. MCP Gateway uses Docker to launch its underlying MCP servers. You can use Docker Desktop or any local Docker engine. To confirm Docker is running, run:

docker version

Step 1: Create configuration file

Create your config file in your desired folder where your app.yaml and mcp.json will be saved to:

mkdir config
cd config

These configuration files control your MCP Gateway deployment, mcp.json defines which MCP servers to launch, while app.yaml sets global settings like authentication, environment variables, and tool customizations. Once you have completed set up, you can populate your app.yaml and mcp.json using the MCP Gateway Control Plane.

Step 2: Run Docker command

In your the config file you just created, run MCP Gateway with the following configuration, exposing ports 9000, 3000, and 5173:

Advanced allowing Docker-in-Docker (Recommended)
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

Without --privileged access, MCP Gateway will not be able to run Dockerized MCP Servers. Exposing port 3000 is optional and used for Prometheus metrics scraping.

Step 3: Go to MCPX control plane

Connect to the MCP Gateway control plane by navigating to http://localhost:5173/.

Step 4: Connect your server

Connect to your MCP server using the MCP Gateway control plane.

In the MCP Gateway control plane, you can connect your MCP sever. Click on Add Server and select a server from the MCP catalog.

Once connected, your selected server will appear in the MCP Gateway control plane. You will be able to use this server’s tools after connecting your clients.

info

You can also choose to add a remote server and authenticate using MCP Gateway OAuth.

Step 5: Connect your client to MCPX

Configure your client to connect to MCP Gateway.

  1. Go to the Settings in your AI agent client (refer to Connect your client to MCP Gateway) and edit the MCP configuration. Make sure to restart your client after saving the configuration.
{
  "mcpServers": {
    "mcpx": {
      "command": "npx",
      "args": [
        "mcp-remote@0.1.36",
        "http://localhost:9000/mcp"
      ]
    }
  }
}

Once connected, you will see your connected agent and server in the MCP Gateway control plane.

What's next?

On this Page