Skip to main content
Feedback

Configure default ports

This page extends the standard MCP Gateway Installation Quick Guide. The goal is to show how to run MCP Gateway on a port different to the default (9000), explain which variables matter, and give a ready to paste example.

Background

By default MCP Gateway is set up to listen on port 9000. In case you do not want to use this port, the container must be started with:

  1. The MCP Gateway server itself listening on a new port.
  2. The front end environment values pointing to the same port.
  3. The container ports published from the host to the new port.

Below is a working pattern for port 8080.

Key variables

These are the relevant environment variables in the image:

  • MCPX_PORT: the port the MCP Gateway server listens on inside the container.
  • MCPX_SERVER_URL: the base URL that other internal parts use to talk to the server. Must use the same port you choose.
  • VITE_MCPX_SERVER_PORT: front end expected server port.
  • VITE_MCPX_SERVER_URL: front end expected server URL, must match the server URL and port.

All four must agree on the same port. If you change it to 8080, update every default value of 9000 to 8080.

Example: run on port 8080

docker run --rm --pull always --privileged -v ./:/lunar/packages/mcpx-server/config -e MCPX_PORT="8080" -e MCPX_SERVER_URL="http://127.0.0.1:8080" -e VITE_MCPX_SERVER_PORT="8080" -e VITE_MCPX_SERVER_URL="http://127.0.0.1:8080" -p 8080:8080 -p 8081:5173 -p 3000:3000 --name mcpx us-central1-docker.pkg.dev/prj-common-442813/mcpx/mcpx:latest

What this does?

  • Inside the container the service runs on 8080 because of MCPX_PORT=8080.
  • The UI service is reached at http://localhost:8081/ because of the exposure of the port 8081 with the override -p 8081:5173.
  • On the host you open port 8080 to the container port 8080 because of -p 8080:8080.
Connecting to your client

If you change the default port, you also need to change the arg port in your agent connection. This means based on the earlier example, that instead of: "http://localhost:9000/mcp" you should use "http://localhost:8080/mcp" in the JSON config.

On this Page