Skip to content

Commit f1f0bad

Browse files
committed
Merge #5452 (#5371) into the rollup
Signed-off-by: cliffhall <[email protected]>
2 parents 6a537e6 + 41a758c commit f1f0bad

12 files changed

Lines changed: 211 additions & 39 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-everything": minor
3+
---
4+
5+
The Streamable HTTP and HTTP+SSE transports now bind the loopback interface (`127.0.0.1`) by default instead of every interface, so a server started over HTTP is no longer reachable from other hosts on the network. Set the new `HOST` environment variable to widen the bind deliberately (`HOST=0.0.0.0`); the container image sets it. The listening line now names the bound address and port. Thanks to TheodorNEngoy for the prototype in #3303.

‎.claude/skills/client-smoke/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -154,8 +154,8 @@ server is listening and exit 4. The wait is bounded and checks that this
154154
server is still alive, so one that fails to bind (the build is missing, the
155155
port was taken in between) ends the run instead of hanging it. The subshell's `EXIT` trap stops the server by pid even when the CLI call
156156
fails; a listener left on the port makes the next run talk to the old build.
157-
By hand in two terminals, the equivalent is waiting for the `listening on
158-
port` line and stopping the server with Ctrl-C.
157+
By hand in two terminals, the equivalent is waiting for the listening line
158+
(`… listening on 127.0.0.1:3917`) and stopping the server with Ctrl-C.
159159

160160
A change to a tool, resource or prompt of `everything` is checked over stdio
161161
and Streamable HTTP. Check HTTP+SSE as well when the change touches transport

‎.claude/skills/local-dev/SKILL.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -71,12 +71,13 @@ PORT=3917 node src/everything/dist/index.js streamableHttp
7171
```
7272

7373
Both HTTP transports listen on `PORT`, default `3001`, so they cannot run side
74-
by side without setting it. Streamable HTTP serves POST, GET and DELETE on
74+
by side without setting it. They bind `HOST`, default `127.0.0.1` (loopback
75+
only); `HOST=0.0.0.0` widens it to every interface. Streamable HTTP serves POST, GET and DELETE on
7576
`/mcp`. HTTP+SSE serves `GET /sse` and `POST /message`; it is deprecated, kept
7677
working, and never the transport to recommend. The two log to different
7778
streams: HTTP+SSE writes everything to stderr, while Streamable HTTP writes its
78-
request and session messages to stdout and its `listening on port` line and
79-
errors to stderr.
79+
request and session messages to stdout and its listening line (which names
80+
the bound `host:port`) and errors to stderr.
8081

8182
## Run the local package the way a user would
8283

‎scripts/smoke-servers.mjs‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -326,9 +326,10 @@ async function exercise(client, server, ctx) {
326326

327327
/**
328328
* A port the OS says is free right now. Probed on the wildcard address, the
329-
* way the servers bind it (`app.listen(PORT)`): a port held on one interface
330-
* only can be bound again on the wildcard without an error, and the client
331-
* would then reach the holder, not the server.
329+
* strictest check: it fails when the port is held on any interface, loopback
330+
* included, which is where the servers bind (`HOST`, pinned to 127.0.0.1
331+
* below). A port held on one interface only could otherwise pass a probe on
332+
* another, and the client would then reach the holder, not the server.
332333
*/
333334
function freePort() {
334335
return new Promise((resolve, reject) => {
@@ -459,7 +460,14 @@ export async function smokeOne(server, transport, ctx, installed) {
459460
let output = "";
460461
const child = spawn(spec.command, spec.args, {
461462
cwd: spec.cwd,
462-
env: envFor(server, ctx, { PORT: String(port) }, installed?.env),
463+
// HOST is pinned to the loopback address the client below connects to,
464+
// so a HOST in the developer's environment cannot move the bind.
465+
env: envFor(
466+
server,
467+
ctx,
468+
{ PORT: String(port), HOST: "127.0.0.1" },
469+
installed?.env,
470+
),
463471
stdio: ["ignore", "pipe", "pipe"],
464472
});
465473
child.stdout.on("data", (chunk) => (output += chunk));

‎src/everything/Dockerfile‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@
1313
#
1414
# The image runs the server over stdio by default (`docker run -i`); give the
1515
# transport name as the argument to run another, e.g. `streamableHttp`, which
16-
# listens on PORT (3001) on every interface so a published port reaches it.
16+
# listens on PORT (3001) on every interface (HOST=0.0.0.0) so a published
17+
# port reaches it.
1718
# The README's "Running with Docker" section has both commands. This repository
1819
# publishes no image: `mcp/everything` on Docker Hub is built by Docker.
1920

@@ -54,6 +55,11 @@ USER node
5455

5556
# The Streamable HTTP (and deprecated HTTP+SSE) transports' default port.
5657
ENV PORT=3001
58+
# Outside a container they bind loopback only (#5371); inside one, loopback is
59+
# the container's own, which a published port cannot reach, so the image
60+
# widens the bind to every interface. `-p 127.0.0.1:…` keeps it off the
61+
# host's network.
62+
ENV HOST=0.0.0.0
5763
EXPOSE 3001
5864

5965
# Both transports close cleanly on SIGINT; node running as PID 1 would ignore

‎src/everything/README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,13 @@ npm run start:streamableHttp
127127

128128
The endpoint is `http://localhost:3001/mcp` (`PORT` overrides the port). It serves 2026-07-28 clients statelessly and 2025-era clients with sessions, from the same URL.
129129

130+
Both HTTP transports (Streamable HTTP and HTTP+SSE) listen on the loopback interface, `127.0.0.1`, by default, so only clients on the same machine can reach them. Set `HOST` to bind another address: `HOST=0.0.0.0` listens on every interface, which exposes the server's tools to every host that can reach the machine, so set it only on a network you trust. The listening line the server prints names the address and port it bound, such as `127.0.0.1:3001`.
131+
132+
| Variable | Default | Effect |
133+
| --- | --- | --- |
134+
| `PORT` | `3001` | The port the HTTP transport listens on |
135+
| `HOST` | `127.0.0.1` | The address it binds; `0.0.0.0` (or `::`) for every interface |
136+
130137
Both HTTP transports (Streamable HTTP and HTTP+SSE) accept browser requests only from a localhost origin: an `Origin` header whose host is `localhost`, `127.0.0.1` or `[::1]`, on any port, such as the MCP Inspector's. A request carrying any other `Origin` is refused with `403 Forbidden`. Clients that send no `Origin` header, which is every non-browser client, are unaffected.
131138

132139
## Running from source with [HTTP+SSE Transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) (deprecated as of [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports))
@@ -195,7 +202,7 @@ docker run -i --rm mcp/everything
195202
docker run --rm -p 127.0.0.1:3001:3001 mcp/everything streamableHttp
196203
```
197204

198-
The endpoint is `http://localhost:3001/mcp`. The server listens on port 3001 on every interface inside the container; `127.0.0.1:` publishes it on the host's loopback only. To use another port, set `PORT` and publish that one (`-e PORT=8080 -p 127.0.0.1:8080:8080`). The localhost-only `Origin` check described above applies inside the container too. `docker stop` ends the server cleanly.
205+
The endpoint is `http://localhost:3001/mcp`. The image sets `HOST=0.0.0.0`, so the server listens on port 3001 on every interface inside the container, which is what lets a published port reach it; `127.0.0.1:` publishes it on the host's loopback only. To use another port, set `PORT` and publish that one (`-e PORT=8080 -p 127.0.0.1:8080:8080`). The localhost-only `Origin` check described above applies inside the container too. `docker stop` ends the server cleanly.
199206

200207
## License
201208

‎src/everything/__tests__/listen.test.ts‎

Lines changed: 85 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,19 @@
55
// success callback; a mocked `listen` would not have reproduced it.
66
// `process.exit` is replaced so the failure path can be observed without ending
77
// the test run, and `console.error` is silenced because that path prints.
8+
// The bind address is checked the same way, on a real socket: loopback unless
9+
// `HOST` says otherwise (#5371).
810

911
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
1012
import { createServer, type Server } from "node:http";
1113
import { once } from "node:events";
1214
import express from "express";
13-
import { listenOrExit } from "../transports/listen.js";
15+
import {
16+
bindHost,
17+
DEFAULT_HOST,
18+
hostAndPort,
19+
listenOrExit,
20+
} from "../transports/listen.js";
1421

1522
const LISTENING = "listening line";
1623

@@ -42,13 +49,13 @@ describe("listenOrExit", () => {
4249
);
4350
});
4451

45-
/** A server holding a port, and the port it holds. */
52+
/** A server holding a port on loopback, and the port it holds. */
4653
async function holdPort(): Promise<number> {
4754
const holder = createServer();
4855
servers.push(holder);
49-
// No host, as the transports bind: a holder on 127.0.0.1 alone would not
50-
// conflict with their wildcard bind on every platform.
51-
holder.listen(0);
56+
// The address the transports bind by default: a holder on another
57+
// interface (the wildcard) would not conflict with it on every platform.
58+
holder.listen(0, DEFAULT_HOST);
5259
await once(holder, "listening");
5360
const address = holder.address();
5461
if (address === null || typeof address === "string") {
@@ -57,31 +64,64 @@ describe("listenOrExit", () => {
5764
return address.port;
5865
}
5966

67+
/** The address `server` is bound to. */
68+
function boundAddress(server: Server): string {
69+
const address = server.address();
70+
if (address === null || typeof address === "string") {
71+
throw new Error("expected a TCP address");
72+
}
73+
return address.address;
74+
}
75+
6076
it("prints the listening line once the port is bound, and does not exit", async () => {
61-
const server = listenOrExit(express(), 0, LISTENING);
77+
const server = listenOrExit(express(), 0, DEFAULT_HOST, LISTENING);
6278
servers.push(server);
6379
await once(server, "listening");
6480

6581
expect(server.listening).toBe(true);
82+
expect(boundAddress(server)).toBe("127.0.0.1");
6683
expect(errorSpy).toHaveBeenCalledWith(LISTENING);
6784
expect(process.exit).not.toHaveBeenCalled();
6885
});
6986

7087
it("reports a port already in use and exits 1 without claiming to listen", async () => {
7188
const port = await holdPort();
72-
const server = listenOrExit(express(), port, LISTENING);
89+
const server = listenOrExit(express(), port, DEFAULT_HOST, LISTENING);
90+
servers.push(server);
91+
92+
expect(await exited).toBe(1);
93+
expect(server.listening).toBe(false);
94+
expect(errorSpy).toHaveBeenCalledWith(
95+
`Failed to start: Port ${port} is already in use on 127.0.0.1. Set PORT to a free port or stop the conflicting process.`,
96+
);
97+
expect(errorSpy).not.toHaveBeenCalledWith(LISTENING);
98+
});
99+
100+
it("binds the host it is given, such as every interface", async () => {
101+
const server = listenOrExit(express(), 0, "0.0.0.0", LISTENING);
102+
servers.push(server);
103+
await once(server, "listening");
104+
105+
expect(boundAddress(server)).toBe("0.0.0.0");
106+
expect(process.exit).not.toHaveBeenCalled();
107+
});
108+
109+
it("reports a host it cannot bind, and exits 1 without claiming to listen", async () => {
110+
// A reserved documentation address (RFC 5737), on no interface here.
111+
const server = listenOrExit(express(), 0, "192.0.2.1", LISTENING);
73112
servers.push(server);
74113

75114
expect(await exited).toBe(1);
76115
expect(server.listening).toBe(false);
77116
expect(errorSpy).toHaveBeenCalledWith(
78-
`Failed to start: Port ${port} is already in use. Set PORT to a free port or stop the conflicting process.`,
117+
"HTTP server encountered an error while starting:",
118+
expect.objectContaining({ code: "EADDRNOTAVAIL" }),
79119
);
80120
expect(errorSpy).not.toHaveBeenCalledWith(LISTENING);
81121
});
82122

83123
it("reports an error that is not an object, and exits 1", async () => {
84-
const server = listenOrExit(express(), 0, LISTENING);
124+
const server = listenOrExit(express(), 0, DEFAULT_HOST, LISTENING);
85125
servers.push(server);
86126
await once(server, "listening");
87127

@@ -95,7 +135,7 @@ describe("listenOrExit", () => {
95135
});
96136

97137
it("reports any other server error and exits 1", async () => {
98-
const server = listenOrExit(express(), 0, LISTENING);
138+
const server = listenOrExit(express(), 0, DEFAULT_HOST, LISTENING);
99139
servers.push(server);
100140
await once(server, "listening");
101141

@@ -111,3 +151,38 @@ describe("listenOrExit", () => {
111151
);
112152
});
113153
});
154+
155+
describe("bindHost", () => {
156+
it("is loopback when HOST is unset", () => {
157+
expect(bindHost({})).toBe("127.0.0.1");
158+
expect(DEFAULT_HOST).toBe("127.0.0.1");
159+
});
160+
161+
it("is loopback when HOST is empty", () => {
162+
expect(bindHost({ HOST: "" })).toBe("127.0.0.1");
163+
});
164+
165+
it("is HOST when it is set", () => {
166+
expect(bindHost({ HOST: "0.0.0.0" })).toBe("0.0.0.0");
167+
});
168+
169+
it("reads the process environment by default", () => {
170+
vi.stubEnv("HOST", "::1");
171+
try {
172+
expect(bindHost()).toBe("::1");
173+
} finally {
174+
vi.unstubAllEnvs();
175+
}
176+
});
177+
});
178+
179+
describe("hostAndPort", () => {
180+
it("joins a host name or IPv4 address and a port", () => {
181+
expect(hostAndPort("127.0.0.1", 3001)).toBe("127.0.0.1:3001");
182+
expect(hostAndPort("localhost", "4567")).toBe("localhost:4567");
183+
});
184+
185+
it("brackets an IPv6 literal", () => {
186+
expect(hostAndPort("::1", 3001)).toBe("[::1]:3001");
187+
});
188+
});

‎src/everything/__tests__/sse.test.ts‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -284,30 +284,50 @@ describe("startSseServer", () => {
284284
async function start() {
285285
vi.resetModules();
286286
const listenOrExit = vi.fn(() => "the http server");
287-
vi.doMock("../transports/listen.js", () => ({ listenOrExit }));
287+
// Only the bind is stubbed; the host is resolved by the real module.
288+
vi.doMock("../transports/listen.js", async (importOriginal) => ({
289+
...(await importOriginal<typeof import("../transports/listen.js")>()),
290+
listenOrExit,
291+
}));
288292
const { startSseServer } = await import("../transports/sse.js");
289293
return { listenOrExit, server: startSseServer() };
290294
}
291295

292296
it("binds PORT when it is set", async () => {
293297
vi.stubEnv("PORT", "4567");
298+
vi.stubEnv("HOST", "");
294299
const { listenOrExit, server } = await start();
295300
expect(error).toHaveBeenCalledWith("Starting SSE server...");
296301
expect(listenOrExit).toHaveBeenCalledWith(
297302
expect.any(Function),
298303
"4567",
299-
"Server is running on port 4567",
304+
"127.0.0.1",
305+
"Server is running on 127.0.0.1:4567",
300306
);
301307
expect(server).toBe("the http server");
302308
});
303309

304-
it("binds 3001 by default", async () => {
310+
it("binds 3001 on loopback by default", async () => {
305311
vi.stubEnv("PORT", "");
312+
vi.stubEnv("HOST", "");
306313
const { listenOrExit } = await start();
307314
expect(listenOrExit).toHaveBeenCalledWith(
308315
expect.any(Function),
309316
3001,
310-
"Server is running on port 3001",
317+
"127.0.0.1",
318+
"Server is running on 127.0.0.1:3001",
319+
);
320+
});
321+
322+
it("binds HOST when it is set, and names it in the listening line", async () => {
323+
vi.stubEnv("PORT", "");
324+
vi.stubEnv("HOST", "0.0.0.0");
325+
const { listenOrExit } = await start();
326+
expect(listenOrExit).toHaveBeenCalledWith(
327+
expect.any(Function),
328+
3001,
329+
"0.0.0.0",
330+
"Server is running on 0.0.0.0:3001",
311331
);
312332
});
313333
});

‎src/everything/__tests__/streamable-http.test.ts‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -614,7 +614,11 @@ describe("startStreamableHttpServer", () => {
614614
async function start() {
615615
vi.resetModules();
616616
const listenOrExit = vi.fn(() => "the http server");
617-
vi.doMock("../transports/listen.js", () => ({ listenOrExit }));
617+
// Only the bind is stubbed; the host is resolved by the real module.
618+
vi.doMock("../transports/listen.js", async (importOriginal) => ({
619+
...(await importOriginal<typeof import("../transports/listen.js")>()),
620+
listenOrExit,
621+
}));
618622
const { startStreamableHttpServer } =
619623
await import("../transports/streamableHttp.js");
620624
const before = process.listeners("SIGINT").length;
@@ -626,24 +630,40 @@ describe("startStreamableHttpServer", () => {
626630

627631
it("binds PORT when it is set and installs the shutdown handler for SIGINT", async () => {
628632
vi.stubEnv("PORT", "4568");
633+
vi.stubEnv("HOST", "");
629634
const { listenOrExit, server, added } = await start();
630635
expect(log).toHaveBeenCalledWith("Starting Streamable HTTP server...");
631636
expect(listenOrExit).toHaveBeenCalledWith(
632637
expect.any(Function),
633638
"4568",
634-
"MCP Streamable HTTP Server listening on port 4568",
639+
"127.0.0.1",
640+
"MCP Streamable HTTP Server listening on 127.0.0.1:4568",
635641
);
636642
expect(server).toBe("the http server");
637643
expect(added).toHaveLength(1);
638644
});
639645

640-
it("binds 3001 by default", async () => {
646+
it("binds 3001 on loopback by default", async () => {
641647
vi.stubEnv("PORT", "");
648+
vi.stubEnv("HOST", "");
642649
const { listenOrExit } = await start();
643650
expect(listenOrExit).toHaveBeenCalledWith(
644651
expect.any(Function),
645652
3001,
646-
"MCP Streamable HTTP Server listening on port 3001",
653+
"127.0.0.1",
654+
"MCP Streamable HTTP Server listening on 127.0.0.1:3001",
655+
);
656+
});
657+
658+
it("binds HOST when it is set, and names it in the listening line", async () => {
659+
vi.stubEnv("PORT", "");
660+
vi.stubEnv("HOST", "0.0.0.0");
661+
const { listenOrExit } = await start();
662+
expect(listenOrExit).toHaveBeenCalledWith(
663+
expect.any(Function),
664+
3001,
665+
"0.0.0.0",
666+
"MCP Streamable HTTP Server listening on 0.0.0.0:3001",
647667
);
648668
});
649669
});

0 commit comments

Comments
 (0)