Businessmcp MCP server

mcp-gateway

Hardening utilities for an MCP gateway — a server that fronts other people's MCP servers.

These are extracted from BusinessMCP's production gateway, which lets a workspace connect third-party MCP servers and re-expose them through one governed endpoint. Fronting someone else's server means fetching a URL a user supplied, on your infrastructure, and that has a small number of ways to go badly wrong. This is what we run.

MIT. No dependencies for the two core modules — two Node builtins and nothing else.

npm install @modelcontextprotocol/client   # only if you use the transport helper

1. The SSRF guard, and the bypass that survived a passing test suite

A gateway takes a URL from a user and fetches it. Without a guard that is a direct path to http://169.254.169.254/ and your cloud credentials.

The obvious implementation checks the host against a list of reserved ranges. Ours did, including IPv4-mapped IPv6:

const mapped = v.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)   // ← the bug

That regex never fired in production. The WHATWG URL parser — new URL(), what every caller actually uses — normalizes IPv6 hosts to their canonical form, and the canonical form of an IPv4-mapped address is hex:

new URL('http://[::ffff:169.254.169.254]/').hostname
// '::ffff:a9fe:a9fe'

The dotted spelling the regex matched is a shape no caller can produce. The unit test passed because it called the guard with the dotted string directly. It was green, and it was meaningless: the guard was only ever exercised through an input the real code path could not generate.

Every one of these reached the fetch:

Adding more prefixes to the list is not the fix. IPv6 has several mechanisms that embed an IPv4 address, and matching text means playing whack-a-mole against a normalizer you do not control. This guard decodes the address to its eight 16-bit groups and checks numerically, unwrapping every embedding it knows (::ffff: mapped, :: compatible, 64:ff9b:: NAT64, 2002:: 6to4) and recursing into the inner IPv4. Undecodable input fails closed — an address you cannot parse is one you cannot vouch for.

import { isPublicHttpUrl, isBlockedIp } from '@businessmcp/mcp-gateway'

await isPublicHttpUrl('http://[::ffff:169.254.169.254]/')  // false
await isPublicHttpUrl('https://api.example.com/mcp')       // true, after resolving every A/AAAA
isBlockedIp('::ffff:a9fe:a9fe')                            // true

isPublicHttpUrl resolves the hostname and requires every returned address to be public, which is a best-effort DNS-rebinding defence. It is not a complete one: a rebind between this check and the socket connect is a real TOCTOU window, and closing it means pinning the resolved IP into the connection. We accept that residual risk and think you should know about it rather than discover it.

There is a second trap this does not solve for you. Validating a host once and then calling fetch(url, { redirect: 'follow' }) is a bypass: the server 302s to http://127.0.0.1/ and the follow is never checked. Follow redirects manually and re-validate every hop.

2. Classify upstream failures — never swallow them

Shortened. The full README is on GitHub.