Allow localhost MCP client URLs

Author: timdp

.changeset/allow-localhost-mcp-client.md

@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+Allow MCP clients to connect to localhost and loopback URLs again for local development while continuing to block private, link-local, and metadata endpoints.

docs/mcp-client.md

@@ -116,11 +116,14 @@ These options are persisted and used when reconnecting after hibernation or afte
 MCP server URLs are validated before connection to prevent Server-Side Request Forgery (SSRF). The following URL targets are blocked:
 
 - Private/internal IP ranges (RFC 1918: `10.x`, `172.16-31.x`, `192.168.x`)
-- Loopback addresses (`127.x`, `::1`)
+- Unspecified addresses (`0.0.0.0`, `::`)
 - Link-local addresses (`169.254.x`, `fe80::`)
 - Cloud metadata endpoints (`169.254.169.254`)
+- IPv6 unique-local addresses (`fc00::/7`)
 
-If you need to connect to an internal MCP server, use the [RPC transport](./mcp-transports.md) with a Durable Object binding instead of HTTP.
+Loopback development URLs such as `localhost`, `127.0.0.1`, and `::1` are allowed.
+
+If you need to connect to another internal MCP server, use the [RPC transport](./mcp-transports.md) with a Durable Object binding instead of HTTP.
 
 ### Return Value
 

packages/agents/src/mcp/client.ts

@@ -36,19 +36,19 @@ const defaultClientOptions: ConstructorParameters<typeof Client>[1] = {
 
 /**
  * Blocked hostname patterns for SSRF protection.
- * Prevents MCP client from connecting to internal/private network addresses.
+ * Prevents MCP client from connecting to internal/private network addresses
+ * while allowing loopback hosts for local development.
  */
 const BLOCKED_HOSTNAMES = new Set([
-  "localhost",
   "0.0.0.0",
-  "[::1]",
   "[::]",
   "metadata.google.internal"
 ]);
 
 /**
  * Check whether a hostname looks like a private/internal IP address.
- * Blocks RFC 1918, link-local, loopback, and cloud metadata endpoints.
+ * Blocks RFC 1918, link-local, unique-local, unspecified,
+ * and cloud metadata endpoints.
  */
 function isBlockedUrl(url: string): boolean {
   let parsed: URL;
@@ -72,8 +72,6 @@ function isBlockedUrl(url: string): boolean {
     if (a === 172 && b >= 16 && b <= 31) return true;
     // 192.168.0.0/16
     if (a === 192 && b === 168) return true;
-    // 127.0.0.0/8 (loopback)
-    if (a === 127) return true;
     // 169.254.0.0/16 (link-local / cloud metadata)
     if (a === 169 && b === 254) return true;
     // 0.0.0.0/8

packages/agents/src/tests/mcp/client-manager.test.ts

@@ -2930,22 +2930,31 @@ describe("MCPClientManager OAuth Integration", () => {
   });
 
   describe("SSRF URL validation", () => {
-    it("should reject localhost URLs", async () => {
+    it("should allow localhost URLs with ports for local development", async () => {
       await expect(
         manager.registerServer("s1", {
           url: "http://localhost:8080/mcp",
-          name: "bad"
+          name: "local"
         })
-      ).rejects.toThrow("Blocked URL");
+      ).resolves.toBe("s1");
     });
 
-    it("should reject 127.x.x.x loopback URLs", async () => {
+    it("should allow 127.0.0.1 loopback URLs", async () => {
       await expect(
         manager.registerServer("s2", {
           url: "http://127.0.0.1/mcp",
-          name: "bad"
+          name: "local-loopback"
         })
-      ).rejects.toThrow("Blocked URL");
+      ).resolves.toBe("s2");
+    });
+
+    it("should allow other 127.x.x.x loopback URLs with custom ports", async () => {
+      await expect(
+        manager.registerServer("s2b", {
+          url: "http://127.12.34.56:9999/mcp",
+          name: "local-loopback-port"
+        })
+      ).resolves.toBe("s2b");
     });
 
     it("should reject RFC 1918 10.x.x.x URLs", async () => {
@@ -3002,13 +3011,13 @@ describe("MCPClientManager OAuth Integration", () => {
       ).rejects.toThrow("Blocked URL");
     });
 
-    it("should reject IPv6 loopback", async () => {
+    it("should allow IPv6 loopback", async () => {
       await expect(
         manager.registerServer("s9", {
           url: "http://[::1]:8080/mcp",
-          name: "bad"
+          name: "local-ipv6"
         })
-      ).rejects.toThrow("Blocked URL");
+      ).resolves.toBe("s9");
     });
 
     it("should reject IPv6 unique local (fc00::/7) URLs", async () => {