Skip to main content
Version: 1.1.x

Configure Default Ports

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

Background​

By default MCPX 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 MCPX 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 MCPX 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 to 8080, every place that says 9000 in the defaults must become 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.