fix(mcp): validate HTTP origins and hosts (CTX7-2533)

Author: fahreddinozcan

.changeset/secure-mcp-http-origin.md

@@ -0,0 +1,5 @@
+---
+"@upstash/context7-mcp": patch
+---
+
+Validate HTTP Origin and Host headers and bind the local HTTP transport to loopback by default.

docs/resources/developer.mdx

@@ -35,6 +35,7 @@ node packages/mcp/dist/index.js
 |------|-------------|---------|
 | `--transport <stdio\|http>` | Transport to use. Use `http` for remote HTTP server or `stdio` for local integration. | `stdio` |
 | `--port <number>` | Port to listen on when using `http` transport. | `3000` |
+| `--host <host>` | Interface to bind when using `http` transport. | `127.0.0.1` |
 | `--api-key <key>` | API key for authentication (or set `CONTEXT7_API_KEY` env var). | - |
 
 <Note>
@@ -74,6 +75,12 @@ You can use the `CONTEXT7_API_KEY` environment variable instead of passing the `
 CONTEXT7_API_KEY=your_api_key_here
 ```
 
+HTTP deployments can set `CONTEXT7_MCP_HOST` to choose the bind interface and
+`CONTEXT7_MCP_ALLOWED_ORIGINS` to add exact, comma-separated browser origins.
+The `--host` flag takes precedence over `CONTEXT7_MCP_HOST`. Keep the default
+loopback bind for local use; set `--host 0.0.0.0` only behind a trusted network
+boundary.
+
 ### MCP Configuration with Environment Variable
 
 ```json

packages/mcp/Dockerfile

@@ -26,4 +26,4 @@ COPY --from=builder /app/packages/mcp/dist ./packages/mcp/dist
 
 WORKDIR /app/packages/mcp
 EXPOSE 8080
-CMD ["node", "dist/index.js", "--transport", "http", "--port", "8080"]
+CMD ["node", "dist/index.js", "--transport", "http", "--port", "8080", "--host", "0.0.0.0"]

packages/mcp/README.md

@@ -1443,6 +1443,7 @@ bun run dist/index.js
 
 - `--transport <stdio|http>` – Transport to use (`stdio` by default). Use `http` for remote HTTP server or `stdio` for local integration.
 - `--port <number>` – Port to listen on when using `http` transport (default `3000`).
+- `--host <host>` – Interface to bind when using `http` transport (default `127.0.0.1`). Set this explicitly, for example to `0.0.0.0`, only when deploying behind a trusted network boundary.
 - `--api-key <key>` – API key for authentication (or set `CONTEXT7_API_KEY` env var). You can get your API key by creating an account at [context7.com/dashboard](https://context7.com/dashboard).
 
 Example with HTTP transport and port 8080:
@@ -1474,6 +1475,13 @@ You can use the `CONTEXT7_API_KEY` environment variable instead of passing the `
 CONTEXT7_API_KEY=your_api_key_here
 ```
 
+HTTP deployments can also set these security options:
+
+- `CONTEXT7_MCP_HOST` – Interface to bind; the CLI `--host` value takes precedence.
+- `CONTEXT7_MCP_ALLOWED_ORIGINS` – Comma-separated additional browser origins allowed to call the server. Values must be exact origins, such as `https://docs.example.com`.
+
+Requests without an `Origin` header, such as normal server-to-server MCP clients, continue to work. When bound to loopback, browser requests must use a loopback origin and the Host header is validated against DNS rebinding. With a non-loopback bind, Context7's production web origins and any explicitly configured origins are allowed.
+
 **Example MCP configuration using environment variable:**
 
 ```json

packages/mcp/src/index.ts

@@ -25,6 +25,7 @@ import {
 } from "./lib/constants.js";
 import { maybeElicitAuthSignIn } from "./lib/auth/auth-prompt.js";
 import { getClientIp } from "./lib/client-ip.js";
+import { createHttpSecurityMiddleware } from "./lib/http-security.js";
 
 /** Default HTTP server port */
 const DEFAULT_PORT = 3000;
@@ -34,13 +35,19 @@ const program = new Command()
   .version(SERVER_VERSION, "-v, --version", "output the current version")
   .option("--transport <stdio|http>", "transport type", "stdio")
   .option("--port <number>", "port for HTTP transport", DEFAULT_PORT.toString())
+  .option(
+    "--host <host>",
+    "host interface for HTTP transport",
+    process.env.CONTEXT7_MCP_HOST || "127.0.0.1"
+  )
   .option("--api-key <key>", "API key for authentication (or set CONTEXT7_API_KEY env var)")
   .allowUnknownOption() // let MCP Inspector / other wrappers pass through extra flags
   .parse(process.argv);
 
 const cliOptions = program.opts<{
   transport: string;
   port: string;
+  host: string;
   apiKey?: string;
 }>();
 
@@ -58,6 +65,7 @@ const TRANSPORT_TYPE = (cliOptions.transport || "stdio") as "stdio" | "http";
 
 // Disallow incompatible flags based on transport
 const passedPortFlag = process.argv.includes("--port");
+const passedHostFlag = process.argv.includes("--host");
 const passedApiKeyFlag = process.argv.includes("--api-key");
 
 if (TRANSPORT_TYPE === "http" && passedApiKeyFlag) {
@@ -67,8 +75,8 @@ if (TRANSPORT_TYPE === "http" && passedApiKeyFlag) {
   process.exit(1);
 }
 
-if (TRANSPORT_TYPE === "stdio" && passedPortFlag) {
-  console.error("The --port flag is not allowed when using --transport stdio.");
+if (TRANSPORT_TYPE === "stdio" && (passedPortFlag || passedHostFlag)) {
+  console.error("The --port and --host flags are not allowed when using --transport stdio.");
   process.exit(1);
 }
 
@@ -78,6 +86,8 @@ const CLI_PORT = (() => {
   return isNaN(parsed) ? undefined : parsed;
 })();
 
+const HTTP_HOST = cliOptions.host;
+
 const requestContext = new AsyncLocalStorage<ClientContext>();
 
 // Global state for stdio mode only
@@ -316,26 +326,9 @@ async function main() {
     const initialPort = CLI_PORT ?? DEFAULT_PORT;
 
     const app = express();
+    app.use(createHttpSecurityMiddleware(HTTP_HOST, process.env.CONTEXT7_MCP_ALLOWED_ORIGINS));
     app.use(express.json());
 
-    app.use((req: express.Request, res: express.Response, next: express.NextFunction) => {
-      res.setHeader("Access-Control-Allow-Origin", "*");
-      res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS,DELETE");
-      // Mcp-Method / Mcp-Name are the SEP-2243 standard headers 2026-07-28
-      // clients send on every request; without them here, browser-based modern
-      // clients fail the CORS preflight. (Mcp-Param-* mirroring is skipped by
-      // browser clients, so those are not needed.)
-      res.setHeader(
-        "Access-Control-Allow-Headers",
-        "Content-Type, MCP-Session-Id, MCP-Protocol-Version, Mcp-Method, Mcp-Name, X-Context7-API-Key, Context7-API-Key, X-API-Key, Authorization"
-      );
-      if (req.method === "OPTIONS") {
-        res.sendStatus(200);
-        return;
-      }
-      next();
-    });
-
     const extractHeaderValue = (value: string | string[] | undefined): string | undefined => {
       if (!value) return undefined;
       return typeof value === "string" ? value : value[0];
@@ -533,7 +526,7 @@ async function main() {
     });
 
     const startServer = (port: number, maxAttempts = 10) => {
-      const httpServer = app.listen(port);
+      const httpServer = app.listen(port, HTTP_HOST);
 
       httpServer.once("error", (err: NodeJS.ErrnoException) => {
         if (err.code === "EADDRINUSE" && port < initialPort + maxAttempts) {
@@ -546,8 +539,9 @@ async function main() {
       });
 
       httpServer.once("listening", () => {
+        const displayHost = HTTP_HOST.includes(":") ? `[${HTTP_HOST}]` : HTTP_HOST;
         console.error(
-          `Context7 Documentation MCP Server v${SERVER_VERSION} running on HTTP at http://localhost:${port}/mcp`
+          `Context7 Documentation MCP Server v${SERVER_VERSION} running on HTTP at http://${displayHost}:${port}/mcp`
         );
       });
     };

packages/mcp/src/lib/http-security.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "vitest";
+import { isLoopbackHost, isLoopbackHostname, isLoopbackOrigin } from "./http-security.js";
+
+describe("loopback request validation", () => {
+  test("recognizes supported bind-host spellings", () => {
+    expect(isLoopbackHostname("localhost")).toBe(true);
+    expect(isLoopbackHostname("localhost.")).toBe(true);
+    expect(isLoopbackHostname("127.0.0.2")).toBe(true);
+    expect(isLoopbackHostname("::1")).toBe(true);
+    expect(isLoopbackHostname("[0:0:0:0:0:0:0:1]")).toBe(true);
+    expect(isLoopbackHostname("0.0.0.0")).toBe(false);
+  });
+
+  test("accepts literal IPv4, IPv6, and localhost origins", () => {
+    expect(isLoopbackOrigin("http://localhost:5173")).toBe(true);
+    expect(isLoopbackOrigin("https://localhost")).toBe(true);
+    expect(isLoopbackOrigin("http://127.0.0.1:8080")).toBe(true);
+    expect(isLoopbackOrigin("http://[::1]:3000")).toBe(true);
+  });
+
+  test("rejects null, malformed, userinfo, and lookalike origins", () => {
+    expect(isLoopbackOrigin("null")).toBe(false);
+    expect(isLoopbackOrigin("not a URL")).toBe(false);
+    expect(isLoopbackOrigin("http://user@localhost:3000")).toBe(false);
+    expect(isLoopbackOrigin("http://localhost.attacker.example")).toBe(false);
+  });
+
+  test("accepts literal loopback Host values with any port", () => {
+    expect(isLoopbackHost("localhost:3000")).toBe(true);
+    expect(isLoopbackHost("127.0.0.1:43117")).toBe(true);
+    expect(isLoopbackHost("[::1]:3000")).toBe(true);
+  });
+
+  test("rejects missing, malformed, userinfo, and lookalike Host values", () => {
+    expect(isLoopbackHost(undefined)).toBe(false);
+    expect(isLoopbackHost("user@localhost")).toBe(false);
+    expect(isLoopbackHost("localhost.attacker.example")).toBe(false);
+    expect(isLoopbackHost("127.0.0.1/path")).toBe(false);
+  });
+});

packages/mcp/src/lib/http-security.ts

@@ -0,0 +1,114 @@
+import type { RequestHandler } from "express";
+import { isIP } from "node:net";
+
+const DEFAULT_HOSTED_ORIGINS = ["https://context7.com", "https://www.context7.com"];
+const ALLOWED_METHODS = "GET,POST,OPTIONS,DELETE";
+// Mcp-Method and Mcp-Name are SEP-2243 headers sent by modern browser clients.
+const ALLOWED_HEADERS =
+  "Content-Type, MCP-Session-Id, MCP-Protocol-Version, Mcp-Method, Mcp-Name, X-Context7-API-Key, Context7-API-Key, X-API-Key, Authorization";
+
+function parseOrigin(value: string): URL | undefined {
+  try {
+    const url = new URL(value);
+    if (
+      url.origin !== value ||
+      !["http:", "https:"].includes(url.protocol) ||
+      url.username ||
+      url.password
+    ) {
+      return undefined;
+    }
+    return url;
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeConfiguredOrigins(value: string | undefined): Set<string> {
+  const origins = (value ?? "")
+    .split(",")
+    .map((origin) => origin.trim())
+    .filter(Boolean);
+
+  return new Set(
+    [...DEFAULT_HOSTED_ORIGINS, ...origins].map((origin) => {
+      const parsed = parseOrigin(origin);
+      if (!parsed) throw new Error(`Invalid allowed origin: '${origin}'`);
+      return parsed.origin;
+    })
+  );
+}
+
+export function isLoopbackHostname(hostname: string): boolean {
+  const unwrapped = hostname
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "")
+    .replace(/\.$/, "");
+  if (unwrapped === "localhost") return true;
+  if (isIP(unwrapped) === 4) return unwrapped.startsWith("127.");
+  if (isIP(unwrapped) === 6) return new URL(`http://[${unwrapped}]`).hostname === "[::1]";
+  return false;
+}
+
+export function isLoopbackOrigin(origin: string): boolean {
+  const url = parseOrigin(origin);
+  return url !== undefined && isLoopbackHostname(url.hostname);
+}
+
+export function isLoopbackHost(hostHeader: string | undefined): boolean {
+  if (!hostHeader) return false;
+
+  try {
+    const url = new URL(`http://${hostHeader}`);
+    return (
+      !url.username &&
+      !url.password &&
+      url.pathname === "/" &&
+      !url.search &&
+      !url.hash &&
+      isLoopbackHostname(url.hostname)
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function createHttpSecurityMiddleware(
+  bindHost: string,
+  additionalHostedOrigins?: string
+): RequestHandler {
+  const isLocal = isLoopbackHostname(bindHost);
+  const hostedOrigins = isLocal ? undefined : normalizeConfiguredOrigins(additionalHostedOrigins);
+  const isOriginAllowed = isLocal
+    ? isLoopbackOrigin
+    : (origin: string) => hostedOrigins?.has(origin) === true;
+
+  return (req, res, next) => {
+    if (isLocal && !isLoopbackHost(req.headers.host)) {
+      res.status(403).json({ error: "forbidden", message: "Untrusted Host header." });
+      return;
+    }
+
+    const origin = req.headers.origin;
+    if (origin && !isOriginAllowed(origin)) {
+      res.status(403).json({ error: "forbidden", message: "Untrusted Origin header." });
+      return;
+    }
+
+    res.vary("Origin");
+    if (origin) {
+      res.setHeader("Access-Control-Allow-Origin", origin);
+      res.setHeader("Access-Control-Allow-Methods", ALLOWED_METHODS);
+      res.setHeader("Access-Control-Allow-Headers", ALLOWED_HEADERS);
+    }
+
+    if (req.method === "OPTIONS") {
+      res.vary("Access-Control-Request-Method");
+      res.vary("Access-Control-Request-Headers");
+      res.sendStatus(204);
+      return;
+    }
+
+    next();
+  };
+}