{"record":{"id":"06ac11cbed05f13d","repo":"different-ai/openwork","slug":"the-address-is-private-or-reserved","errorCode":null,"errorMessage":"the address is private or reserved","messagePattern":"the address is private or reserved","errorType":"exception","errorClass":"LocalManagedMcpPrivateUrlError","httpStatus":null,"severity":"error","filePath":"apps/server/src/local-managed-mcp-url-guard.ts","lineNumber":178,"sourceCode":"      }\n      const first = addresses[0];\n      callback(null, first.address, first.family);\n    }, (error: unknown) => {\n      callback(error instanceof Error ? error : new Error(\"Managed MCP hostname lookup failed.\"), []);\n    });\n  };\n}\n\nexport async function assertLocalManagedMcpUrl(rawUrl: string): Promise<void> {\n  const url = parseHttpUrl(rawUrl);\n  if (allowPrivateUrls()) return;\n  if (url.protocol !== \"https:\") {\n    throw new LocalManagedMcpPrivateUrlError(rawUrl, \"managed MCP egress requires HTTPS\");\n  }\n  const hostname = url.hostname.replace(/^\\[|\\]$/g, \"\");\n  if (isIP(hostname)) {\n    if (isLocalManagedMcpPrivateAddress(hostname)) {\n      throw new LocalManagedMcpPrivateUrlError(rawUrl, \"the address is private or reserved\");\n    }\n    return;\n  }\n  let addresses: LookupAddress[];\n  try {\n    addresses = await resolveAddresses(hostname, { all: true, verbatim: true });\n  } catch {\n    throw new LocalManagedMcpPrivateUrlError(rawUrl, \"the hostname does not resolve\");\n  }\n  validateResolvedAddresses(hostname, addresses);\n}\n\ntype FetchLike = (url: string | URL, init?: RequestInit) => Promise<Response>;\nconst REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);\nconst guardedDispatcher = new Agent({\n  connect: {\n    lookup: createLocalManagedMcpPublicLookup(),\n    // Node's 250 ms family-attempt default is too aggressive for otherwise","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/apps/server/src/local-managed-mcp-url-guard.ts#L160-L196","documentation":"After confirming HTTPS, assertLocalManagedMcpUrl resolves the hostname and rejects addresses that are private, loopback, link-local, or otherwise reserved (checked via isLocalManagedMcpPrivateAddress). This prevents SSRF-style egress to internal infrastructure from the managed MCP runtime.","triggerScenarios":"Calling createLocalManagedMcpConnection or withRemoteClient with a URL whose hostname is a literal IP (e.g. 127.0.0.1, 10.x.x.x, 192.168.x.x, ::1) that isLocalManagedMcpPrivateAddress classifies as private/reserved, while private URLs are not allowed.","commonSituations":"Configuring an MCP server by internal cluster IP instead of its public hostname; pointing at 127.0.0.1 for a locally running server; IPv6 literals like [::1] (brackets are stripped before the check); Docker-internal addresses like 172.17.x.x.","solutions":["Use the public DNS hostname of the MCP server instead of a private IP","If the connection is intentionally local/internal, enable the allowPrivateUrls() switch for that environment","Check for typos in the configured IP (e.g. 10.0.0.1 vs a public address)","Verify the server publishes a public endpoint reachable over HTTPS"],"exampleFix":"// before\nawait createLocalManagedMcpConnection({ url: \"https://192.168.1.10/mcp\" });\n// after\nawait createLocalManagedMcpConnection({ url: \"https://mcp.internal-gateway.example.com/mcp\" });","handlingStrategy":"validation","validationCode":"import { isIP } from \"node:net\";\nconst host = new URL(rawUrl).hostname.replace(/^\\[|\\]$/g, \"\");\nif (isIP(host) && (host === \"127.0.0.1\" || host.startsWith(\"10.\") || host.startsWith(\"192.168.\") || host === \"::1\")) {\n  throw new Error(`Refusing private address for managed MCP: ${host}`);\n}","typeGuard":"function isPublicLiteralIp(hostname: string): boolean {\n  return isIP(hostname) === 0 || !isLocalManagedMcpPrivateAddress(hostname);\n}","tryCatchPattern":"try {\n  await createLocalManagedMcpConnection({ url });\n} catch (error) {\n  if (error instanceof LocalManagedMcpPrivateUrlError && error.message === \"the address is private or reserved\") {\n    // prompt user to provide the public hostname of the MCP server\n  }\n  throw error;\n}","preventionTips":["Configure servers by public DNS name, never by internal IP","Never hardcode loopback or RFC1918 addresses in production config","Enable private-URL allowance only in explicitly local/dev environments","Document which addresses are considered private when planning internal deployments"],"tags":["security","network","ssrf","private-address"],"backgroundTag":"private-address-egress-blocked","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}