Connecting local MCP servers to MCP Gateway

You can run MCP servers from source and connect them to MCP Gateway locally. This gives you full control over the server code and behavior.

This topic uses the example of Todoist MCP server as a local server.

Step 1: Clone and build the server

Download the server repository and build it locally.

# Clone the server repository
git clone https://github.com/Doist/todoist-mcp.git

# Install dependencies and build
cd todoist-mcp
npm install
npm run build
cd ..

This produces a compiled server in todoist-mcp/dist.

Step 2: Prepare directory structure

Organize your project folders for running MCP Gateway.

# Create the servers directory
mkdir -p servers

# Copy the built server to the servers directory
cp -r todoist-mcp ./servers/todoist-mcp

# Create a config directory for your mcp.json file
mkdir -p config

Step 3: Configure mcp.json

Define your local server inside mcp.json.

nano config/mcp.json

Example mcp.json:

In this file, make sure that the path matches the location inside the Docker container.

{
  "mcpServers": {
    "todoist-mcp": {
      "command": "node",
      "args": ["/lunar/servers/todoist-mcp/bin/index.js"],
      "env": {
          "TODOIST_API_KEY": "YOUR_TODOIST_API_KEY"
      }
    }
  }
}

Step 4: Run MCP Gateway with Docker

Mount the local config and server folders into the container.

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