Merge pull request #417 from apollographql/AIR-42

Change default port from 5000 to 8000

Author: DaleSeo

.changesets/breaking_defalut_port_8000.md

@@ -0,0 +1,20 @@
+### Change default port from 5000 to 8000 - @DaleSeo PR #417
+
+The default server port has been changed from `5000` to `8000` to avoid conflicts with common development tools and services that typically use port 5000 (such as macOS AirPlay, Flask development servers, and other local services).
+
+**Migration**: If you were relying on the default port 5000, you can continue using it by explicitly setting the port in your configuration file or command line arguments.
+
+- Before 
+
+```yaml
+transport:
+  type: streamable_http
+```
+
+- After
+
+```yaml
+transport:
+  type: streamable_http
+  port: 5000
+```

crates/apollo-mcp-server/src/server.rs

@@ -94,7 +94,7 @@ impl Transport {
     }
 
     fn default_port() -> u16 {
-        5000
+        8000
     }
 
     fn default_stateful_mode() -> bool {

docs/source/config-file.mdx

@@ -170,7 +170,7 @@ The available fields depend on the value of the nested `type` key:
 | :-------------- | :-------------------- | :--------- | :------------------------------------------------------------------------ |
 | `type`          | `"streamable_http"`   |            | Host the MCP server on the configuration, using streamable HTTP messages. |
 | `address`       | `127.0.0.1` (default) | `IpAddr`   | The IP address to bind to                                                 |
-| `port`          | `5000` (default)      | `u16`      | The port to bind to                                                       |
+| `port`          | `8000` (default)      | `u16`      | The port to bind to                                                       |
 | `stateful_mode` | `true` (default)      | `bool`     | Flag to enable or disable stateful mode and session management.           |
 
 ##### SSE (Deprecated, use StreamableHTTP)
@@ -179,7 +179,7 @@ The available fields depend on the value of the nested `type` key:
 | :-------- | :-------------------- | :--------- | :--------------------------------------------------------------------------------------------------------------- |
 | `type`    | `"sse"`               |            | Host the MCP server on the supplied config, using SSE for communication. Deprecated in favor of `StreamableHTTP` |
 | `address` | `127.0.0.1` (default) | `IpAddr`   | The IP address to bind to                                                                                        |
-| `port`    | `5000` (default)      | `u16`      | The port to bind to                                                                                              |
+| `port`    | `8000` (default)      | `u16`      | The port to bind to                                                                                              |
 
 ### Auth
 

docs/source/cors.mdx

@@ -26,7 +26,7 @@ The following snippet includes an example of each option (use either `allow_any_
 ```yaml title="mcp.yaml"
 transport:
   type: streamable_http
-  port: 5000
+  port: 8000
 
 cors:
   # Enable CORS support
@@ -207,7 +207,7 @@ Here's a simple example of connecting to Apollo MCP Server from a browser:
 
 ```javascript
 async function connectToMCP() {
-  const response = await fetch("http://127.0.0.1:5000/mcp", {
+  const response = await fetch("http://127.0.0.1:8000/mcp", {
     method: "POST",
     headers: {
       Accept: "application/json, text/event-stream",

docs/source/debugging.mdx

@@ -65,7 +65,7 @@ schema:
 transport:
   type: streamable_http
   address: 127.0.0.1
-  port: 5000
+  port: 8000
 ```
 
 ```sh
@@ -81,6 +81,6 @@ npx @modelcontextprotocol/inspector
 1. In a browser, go to the URL returned by Inspector, then fill in the details:
 
    - **Transport Type**: Select `Streamable HTTP`
-   - **URL**: Enter `http://127.0.0.1:5000/mcp`, where the port must match the `transport.port` option
+   - **URL**: Enter `http://127.0.0.1:8000/mcp`, where the port must match the `transport.port` option
 
 1. Click **Connect** and **List Tools**. You should see the tools for the operations you provided.

docs/source/deploy.mdx

@@ -19,12 +19,12 @@ For most production deployments, use the all-in-one [Apollo Runtime Container](/
 
 ### Deploy the Apollo Runtime Container
 
-The Apollo Runtime Container includes all services necessary to serve GraphQL and MCP requests, including Apollo Router and Apollo MCP Server. Both port `4000` (GraphQL) and `5000` (MCP) are exposed.
+The Apollo Runtime Container includes all services necessary to serve GraphQL and MCP requests, including Apollo Router and Apollo MCP Server. Both port `4000` (GraphQL) and `8000` (MCP) are exposed.
 
 ```bash title="Deploy with GraphOS (Recommended)"
 docker run \
   -p 4000:4000 \
-  -p 5050:5000 \
+  -p 8000:8000 \
   --env APOLLO_GRAPH_REF="<your-graph-ref>" \
   --env APOLLO_KEY="<your-graph-api-key>" \
   --env MCP_ENABLE=1 \
@@ -52,7 +52,7 @@ Use the standalone Apollo MCP Server container if you already have a GraphQL API
 
 Apollo MCP Server is available as a standalone Docker container. Container images are downloadable using the image `ghcr.io/apollographql/apollo-mcp-server`.
 
-By default, the container expects all schema and operation files to be present in the `/data` directory within the container and that clients use Streamable HTTP transport on container port `5050`.
+By default, the container expects all schema and operation files to be present in the `/data` directory within the container and that clients use Streamable HTTP transport on container port `8000`.
 
 Here's an example `docker run` command that runs Apollo MCP Server for an example using [TheSpaceDevs graph](https://thespacedevs-production.up.railway.app/):
 
@@ -71,7 +71,7 @@ schema:
 docker run \
   -it --rm \
   --name apollo-mcp-server \
-  -p 5050:5000 \
+  -p 8000:8000 \
   -v <path/to>/mcp_config.yaml:/config.yaml \
   -v $PWD/graphql/TheSpaceDevs:/data \
   --pull always \

docs/source/guides/auth-auth0.mdx

@@ -31,7 +31,7 @@ This guide uses [Auth0](https://auth0.com/) as the Identity Provider.
 1. In your dashboard, navigate to **Applications** -> **APIs**.
 1. Click **Create API**.
 1. Give it a friendly name like `MCP Auth API`.
-1. For the **Identifier** field, Auth0 recommends using a URL. This identifier is used in the MCP server configuration later as the `audience` property. For this guide, use `http://localhost:5000/mcp-example`.
+1. For the **Identifier** field, Auth0 recommends using a URL. This identifier is used in the MCP server configuration later as the `audience` property. For this guide, use `http://localhost:8000/mcp-example`.
 1. Leave the defaults for the rest of the fields and click **Create**.
 1. Navigate to your dashboard **Settings**.
    1. Under **General** -> **API Authorization Settings**, set the **Default Audience** to the `Identifier` you chose.
@@ -89,14 +89,14 @@ Configure the MCP server to use the Auth0 instance for authentication.
          - https://<AUTH0 DOMAIN> # Fill in your Auth0 domain
        audiences:
          - <AUTH0 DEFAULT AUDIENCE> # Fill in your Auth0 Identifier
-       resource: http://127.0.0.1:5000/mcp
+       resource: http://127.0.0.1:8000/mcp
        scopes:
          - read:users # Adjust scopes as needed
    ```
 
 1. Replace the `<AUTH0 DOMAIN>` with your own Auth0 domain from earlier.
 
-1. Replace the `<AUTH0 DEFAULT AUDIENCE>` with the matching `Identifier` you set when creating the Auth0 API. In this guide, you used `http://localhost:5000/mcp-example`.
+1. Replace the `<AUTH0 DEFAULT AUDIENCE>` with the matching `Identifier` you set when creating the Auth0 API. In this guide, you used `http://localhost:8000/mcp-example`.
 
 Your MCP server is now configured to use Auth0 for authentication.
 
@@ -188,7 +188,7 @@ You need a graph's credentials and a valid GraphOS plan to use the router's auth
 
    The browser should open automatically with a proxy auth token.
 
-1. In the MCP Inspector, select `Streamable HTTP` as the Transport Type and enter `http://127.0.0.1:5000/mcp` as the URL.
+1. In the MCP Inspector, select `Streamable HTTP` as the Transport Type and enter `http://127.0.0.1:8000/mcp` as the URL.
 1. Click **Connect**. This triggers the OAuth flow, and you are redirected to the Auth0 login page.
 1. Log in with the credentials you set up in the Auth0 connection and allow MCP Inspector access.
 1. After you connect, the browser redirects back to MCP Inspector.
@@ -241,7 +241,7 @@ Then, continue with the following steps:
 | "What would you like to configure?"                         | "Add Extension"                            |
 | "What type of extension would you like to add?"             | "Command Line Extension"                   |
 | "What's the name of this extension?"                        | "mcp-auth-quickstart"                      |
-| "What command should be run?"                               | `npx mcp-remote http://127.0.0.1:5000/mcp` |
+| "What command should be run?"                               | `npx mcp-remote http://127.0.0.1:8000/mcp` |
 | Other prompts (timeout, description, environment variables) | Use the default values                     |
 
 1. To start Goose, type `goose`. This will open a browser window and send you through the auth flow.
@@ -255,8 +255,8 @@ Then, continue with the following steps:
 
 #### MCP Server Won't Start
 
-- **Error**: "Port 5000 is already in use"
-  - Solution: Kill any existing processes using port 5000 or specify a different port with the `transport.port` option or `APOLLO_MCP_TRANSPORT__PORT` env variable
+- **Error**: "Port 8000 is already in use"
+  - Solution: Kill any existing processes using port 8000 or specify a different port with the `transport.port` option or `APOLLO_MCP_TRANSPORT__PORT` env variable
 - **Error**: "Failed to load supergraph configuration"
   - Solution: Verify you're running the command from the repo root directory
   - Solution: Check that the path to `supergraph.yaml` is correct
@@ -269,7 +269,7 @@ Then, continue with the following steps:
 
 - **Error**: "Failed to connect to server"
   - Solution: Ensure the MCP server is running (check terminal output)
-  - Solution: Verify you're using the correct URL (`http://127.0.0.1:5000/mcp`)
+  - Solution: Verify you're using the correct URL (`http://127.0.0.1:8000/mcp`)
   - Solution: Check if your firewall is blocking the connection
 
 ### Infinite loop during OAuth flow

docs/source/health-checks.mdx

@@ -15,7 +15,7 @@ Health checks are only available when using the `streamable_http` transport and
 transport:
   type: streamable_http
   address: 127.0.0.1
-  port: 5000
+  port: 8000
 health_check:
   enabled: true
   path: /health

docs/source/quickstart.mdx

@@ -61,12 +61,12 @@ You can start your MCP server locally with `rover dev`.
 
     </Tabs>
 
-1. You should see some output indicating that the GraphQL server is running at `http://localhost:4000` and the MCP server is running at `http://127.0.0.1:5050`.
+1. You should see some output indicating that the GraphQL server is running at `http://localhost:4000` and the MCP server is running at `http://127.0.0.1:8000`.
 
 1. In a new terminal window, run the MCP Inspector to verify the server is running:
 
     ```terminal showLineNumbers=false
-    npx @modelcontextprotocol/inspector http://127.0.0.1:5050/mcp --transport http
+    npx @modelcontextprotocol/inspector http://127.0.0.1:8000/mcp --transport http
     ```
 
 1. This will automatically open your browser to `http://127.0.0.1:6274`.
@@ -94,7 +94,7 @@ Copy the configuration:
       "command": "npx",
       "args": [
         "mcp-remote",
-        "http://127.0.0.1:5050/mcp"
+        "http://127.0.0.1:8000/mcp"
       ]
     }
   }
@@ -107,7 +107,7 @@ Copy the configuration:
 Install using the CLI:
 
 ```bash
-claude mcp add apollo-mcp npx mcp-remote http://127.0.0.1:5050/mcp
+claude mcp add apollo-mcp npx mcp-remote http://127.0.0.1:8000/mcp
 ```
 </ExpansionPanel>
 
@@ -127,7 +127,7 @@ Or install manually:
 1. Go to **Cursor Settings** → **MCP** → **Add new MCP Server**
 2. Name: `Apollo MCP` (choose a title)
 3. Command: `npx`
-4. Arguments: `["mcp-remote", "http://127.0.0.1:5050/mcp"]`
+4. Arguments: `["mcp-remote", "http://127.0.0.1:8000/mcp"]`
 </ExpansionPanel>
 
 <ExpansionPanel title="Goose">
@@ -147,21 +147,21 @@ default:
           command: npx
           args:
             - mcp-remote
-            - http://127.0.0.1:5050/mcp
+            - http://127.0.0.1:8000/mcp
 ```
 
 Or use the Goose CLI to add the MCP server:
 
 ```bash
-goose mcp add apollo-mcp npx mcp-remote http://127.0.0.1:5050/mcp
+goose mcp add apollo-mcp npx mcp-remote http://127.0.0.1:8000/mcp
 ```
 </ExpansionPanel>
 
 <ExpansionPanel title="Cline (VS Code Extension)">
 1. Go to **Advanced settings** → **Extensions** → **Add custom extension**
 2. Name: `Apollo MCP`
 3. Type: **STDIO**
-4. Command: `npx mcp-remote http://127.0.0.1:5050/mcp`
+4. Command: `npx mcp-remote http://127.0.0.1:8000/mcp`
 </ExpansionPanel>
 
 <ExpansionPanel title="OpenCode">
@@ -176,7 +176,7 @@ Edit `~/.config/opencode/opencode.json`:
       "command": [
         "npx",
         "mcp-remote",
-        "http://127.0.0.1:5050/mcp"
+        "http://127.0.0.1:8000/mcp"
       ],
       "enabled": true
     }
@@ -189,7 +189,7 @@ Edit `~/.config/opencode/opencode.json`:
 1. Go to **Windsurf Settings → MCP → Add new MCP Server**
 2. Name: `Apollo MCP`
 3. Command: `npx`
-4. Arguments: `["mcp-remote", "http://127.0.0.1:5050/mcp"]`
+4. Arguments: `["mcp-remote", "http://127.0.0.1:8000/mcp"]`
 
 Alternatively, edit your Windsurf configuration file directly:
 
@@ -200,7 +200,7 @@ Alternatively, edit your Windsurf configuration file directly:
       "command": "npx",
       "args": [
         "mcp-remote",
-        "http://127.0.0.1:5050/mcp"
+        "http://127.0.0.1:8000/mcp"
       ]
     }
   }
@@ -265,7 +265,7 @@ Your project includes a pre-configured `mcp.Dockerfile` for easy deployment. Thi
 1. Run locally:
 
     ```bash
-    docker run -p 4000:4000 -p 5050:5000 \
+    docker run -p 4000:4000 -p 8000:8000 \
       -e APOLLO_KEY=$APOLLO_KEY \
       -e APOLLO_GRAPH_REF=$APOLLO_GRAPH_REF \
       -e MCP_ENABLE=1 \
@@ -280,7 +280,7 @@ Your project includes a pre-configured `mcp.Dockerfile` for easy deployment. Thi
 | ---------------------------- | ------------------------------- | -------- |
 | `APOLLO_KEY`                 | Your graph's API key            | Yes      |
 | `APOLLO_GRAPH_REF`           | Your graph reference            | Yes      |
-| `APOLLO_MCP_TRANSPORT__PORT` | MCP server port (default: 5000) | No       |
+| `APOLLO_MCP_TRANSPORT__PORT` | MCP server port (default: 8000) | No       |
 | `APOLLO_ROUTER_PORT`         | Router port (default: 4000)     | No       |
 
 For more deployment options, see the [Deploy the MCP Server](/apollo-mcp-server/deploy) page.
@@ -312,7 +312,7 @@ After deploying, update your MCP client configuration to use the deployed URL:
 
 **Connection refused errors:**
 - Confirm the server is running on the correct port
-- Verify firewall settings allow connections to localhost:5050
+- Verify firewall settings allow connections to localhost:8000
 - For remote connections, ensure the host is set to `0.0.0.0` in your config
 
 **Authentication issues:**

docs/source/run.mdx

@@ -117,7 +117,7 @@ The container sets a few defaults for ease of use:
 
 - **Working Directory is `/data`**: Make sure to mount static schemas / operations to this location
   using the volume flag when running [(`-v` / `--volume`)](https://docs.docker.com/reference/cli/docker/container/run/#volume).
-- **HTTP Streamable Transport on port 5000**: Make sure to export container port 5000 for HTTP Streamable connections to
+- **HTTP Streamable Transport on port 8000**: Make sure to export container port 8000 for HTTP Streamable connections to
   the MCP server using the port flag when running [(`-p` / `--port`)](https://docs.docker.com/reference/cli/docker/container/run/#publish)
 
 </Note>
@@ -128,7 +128,7 @@ Run the following Docker command to start the MCP Server, replacing the values f
 docker run \
   -it --rm \
   --name apollo-mcp-server \
-  -p 5000:5000 \
+  -p 8000:8000 \
   -v <PATH/TO/CONFIG/FILE>:/config.yaml \
   -v <PATH/TO/PROJECT/ROOT>:/data \
   --pull always \
@@ -139,20 +139,20 @@ This command:
 
 - Starts an MCP Server in a Docker container
 - Maps configuration files into the proper place for the Apollo MCP Server container
-- Forwards port 5000 for accessing the MCP Server
+- Forwards port 8000 for accessing the MCP Server
 
 ## With the Apollo Runtime Container
 
 The Apollo Runtime Container runs both the MCP Server and the [Apollo Router](https://www.apollographql.com/docs/graphos/routing) in a single container. It's useful for local development, testing, and production deployments.
 
 The Apollo Runtime container includes all services necessary to serve GraphQL and MCP requests, including the Router and MCP Server. It is the easiest way to operate a GraphQL API with MCP support.
 
-To serve both MCP and GraphQL requests, both port `4000` and `5000` will need to be exposed. An example command which retrieves the schema from Uplink is:
+To serve both MCP and GraphQL requests, both port `4000` and `8000` will need to be exposed. An example command which retrieves the schema from Uplink is:
 
 ```bash title="Docker" {3, 6}
 docker run \
   -p 4000:4000 \
-  -p 5000:5000 \
+  -p 8000:8000 \
   --env APOLLO_GRAPH_REF="<your-graph-ref>" \
   --env APOLLO_KEY="<your-graph-api-key>" \
   --env MCP_ENABLE=1 \