{"record":{"id":"e9b8b707c74d1ba0","repo":"different-ai/openwork","slug":"mcp-url-blocked","errorCode":"MCP_URL_BLOCKED","errorMessage":"MCP_URL_BLOCKED","messagePattern":"MCP_URL_BLOCKED","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts","lineNumber":1201,"sourceCode":"        ? \"Retry the capability, and reduce provider latency for this tool if it keeps running past the bounded deadline.\"\n        : \"Reduce provider latency or catalog pagination so the complete MCP lifecycle finishes within the bounded deadline, then retry.\",\n    }\n  }\n  if (error instanceof ExternalMcpResponseBodyLimitError) {\n    return {\n      phase: fallbackPhase,\n      category: \"response_too_large\",\n      code: \"MCP_RESPONSE_BODY_LIMIT\",\n      retryable: false,\n      actionOwner: \"provider_admin\",\n      operatorAction: \"Reduce the provider response size, tool catalog, or event-stream payload before retrying.\",\n    }\n  }\n  if (error instanceof PrivateUrlError) {\n    return {\n      phase: \"CONFIGURATION\",\n      category: \"security_blocked\",\n      code: \"MCP_URL_BLOCKED\",\n      retryable: false,\n      actionOwner: \"organization_admin\",\n      operatorAction: \"Use a public HTTPS MCP URL or change the deployment's private-network policy through security review.\",\n    }\n  }\n  if (hasForbiddenPortMessage(error)) {\n    return {\n      phase: \"CONFIGURATION\",\n      category: \"unsupported_endpoint_port\",\n      code: \"MCP_FETCH_FORBIDDEN_PORT\",\n      retryable: false,\n      actionOwner: \"organization_admin\",\n      operatorAction: \"Use the provider's supported HTTPS MCP port or place the endpoint behind a standard HTTPS listener.\",\n    }\n  }\n\n  const code = errorCode(error)\n  if (code) {","sourceCodeStart":1183,"sourceCodeEnd":1219,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts#L1183-L1219","documentation":"MCP_URL_BLOCKED is raised when the configured MCP endpoint fails the gateway's SSRF guard, thrown as PrivateUrlError and classified as CONFIGURATION / security_blocked. The gateway deliberately refuses to call private/internal network addresses (loopback, RFC1918, link-local, metadata endpoints) from external MCP sources. It is non-retryable and owned by the organization admin since it requires either a public URL or an explicit policy change through security review.","triggerScenarios":"Registering or invoking an external MCP capability whose URL resolves to a private address — e.g. http://localhost:8080/mcp, http://10.x.x.x/mcp, http://192.168.x.x/mcp, or a hostname that DNS-resolves to a private IP — triggering the PrivateUrlError check during request setup.","commonSituations":"Developers pointing the external MCP source at a local dev server; internal-only providers behind VPC addresses; DNS names that resolve to private IPs inside the deployment network; attempts to reach cloud metadata services (accidental or malicious).","solutions":["Use a public HTTPS MCP URL that the gateway can reach from its network.","If internal access is genuinely required, change the deployment's private-network policy through security review to allowlist the address.","Expose the internal MCP server via an approved public gateway/tunnel that passes the private-URL check."],"exampleFix":"// before: private dev URL in external source config\n{ \"url\": \"http://localhost:8080/mcp\" }\n// after\n{ \"url\": \"https://mcp.mycompany.example.com/mcp\" }","handlingStrategy":"validation","validationCode":"// pre-flight the configured URL against the private-address rules\nfunction isPublicHttpsUrl(raw: string): boolean {\n  const u = new URL(raw)\n  if (u.protocol !== 'https:') return false\n  const host = u.hostname\n  if (host === 'localhost' || host.endsWith('.local')) return false\n  if (/^(10\\.|127\\.|192\\.168\\.|169\\.254\\.|172\\.(1[6-9]|2\\d|3[01])\\.)/.test(host)) return false\n  return true\n}\nif (!isPublicHttpsUrl(config.url)) throw new Error('MCP URL must be public HTTPS')","typeGuard":"function isUrlBlocked(d: { code: string }): boolean {\n  return d.code === 'MCP_URL_BLOCKED'\n}","tryCatchPattern":"try {\n  return await connectExternalMcp(config)\n} catch (e) {\n  if (isUrlBlocked(e.diagnostic)) {\n    // non-retryable: configuration must change; do not attempt to bypass the SSRF guard\n    throw new Error(`blocked private MCP URL: ${config.url} — use public HTTPS or request a policy exception`)\n  }\n  throw e\n}","preventionTips":["Only register public HTTPS URLs for external MCP sources.","Reach internal MCP servers through an approved public gateway rather than private addresses.","If an internal address is truly required, request a private-network policy exception through security review before configuring it."],"tags":["mcp","ssrf","security","private-network","configuration"],"backgroundTag":"private-url-blocked","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}