URL Rewriting

AISIX AI Gateway can rewrite the request path before routing. An ordered list of rewrite rules runs at the entry of the proxy listener: the first rule whose match regex matches the request path rewrites it, and the request then flows through the normal endpoint — authentication, access control, rate limits, and telemetry apply exactly as if the client had sent the rewritten path.

Use URL rewriting when existing clients are configured with URL shapes AISIX does not serve natively — for example, gateways that expose one URL per MCP server, or internal conventions like a health path an external monitor already probes.

Configure Rewrite Rules

Rewrite rules are startup configuration in config.yaml, under the proxy block:

proxy:
  addr: "0.0.0.0:3000"
  url_rewrites:
    - name: per-server-mcp-compat
      match: "^/mcp-servers/([^/]+)/mcp$"
      rewrite: "/mcp/$1"

Field	Required	Description
name	No	Label used in gateway logs when the rule fires.
match	Yes	Regex tested against the raw, percent-encoded request path (never the query string), with no decoding or normalization. Anchor with ^ and $ to match the whole path.
rewrite	Yes	Replacement for the matched portion of the path. $1 … expand numbered capture groups, and ${server} expands a named group defined as (?P<server>…) in match. Use the braced form (${1}text) when literal text follows a reference. Must not contain ?, #, or whitespace — the query string is preserved automatically.

Changing rules requires a gateway restart, like any other startup configuration. Startup validation rejects broken rules with an error naming the rule — invalid regexes, references to capture groups the pattern does not define, forbidden characters in the template, and patterns that would match the empty string — so a typo surfaces immediately instead of as silently mis-routed traffic.

When the gateway is configured purely through environment variables, such as a Helm-managed deployment, set the whole list as one JSON array:

AISIX_PROXY__URL_REWRITES='[{"name":"per-server-mcp-compat","match":"^/mcp-servers/([^/]+)/mcp$","rewrite":"/mcp/$1"}]'

How Rules Are Applied

• Rules run in declaration order; the first match wins and is applied once — a rewritten path is never fed back through the rule list.
• rewrite replaces the matched portion of the path. With an unanchored match, the unmatched prefix and suffix are preserved.
• The query string is preserved as sent.
• A request no rule matches is passed through untouched, and canonical paths keep working alongside the rewritten shapes.
• Rewriting applies to every request on the proxy listener. The admin and metrics listeners are not affected.

Rewriting selects which gateway endpoint serves the request; it never bypasses governance. The rewritten request is authenticated and authorized by its target endpoint, and metrics and access logs record the rewritten route.

Example: Serve Per-Server MCP URLs

Some gateways expose each MCP server at its own URL, such as /mcp-servers/github/mcp, and clients call tools by their original names. AISIX serves that contract natively on its per-server MCP endpoint /mcp/{server} — one rewrite rule connects the legacy URL shape to it:

proxy:
  url_rewrites:
    - name: per-server-mcp-compat
      match: "^/mcp-servers/([^/]+)/mcp$"
      rewrite: "/mcp/$1"

A client configured with https://gateway.example.com/mcp-servers/github/mcp now reaches /mcp/github, lists the github server's tools under their original names, and calls them with those names — no client changes, and the caller API key's tool access, rate limits, budgets, and guardrails apply unchanged.

Only the URL shapes you declare are served: with the rule above, /mcp-servers/github/sse matches nothing and returns 404 rather than being silently routed.

Example: Alias an Arbitrary Path

Rules are not MCP-specific. Any path can map onto any proxy endpoint:

proxy:
  url_rewrites:
    - name: legacy-health
      match: "^/healthz-compat$"
      rewrite: "/livez"