feat(proxy): entry-level URL rewriting via proxy.url_rewrites

config.example.yaml

@@ -51,6 +51,18 @@ proxy:
   #   trusted_proxies: ["10.0.0.0/8", "127.0.0.1/32"]
   #   recursive: true
   #   header: x-forwarded-for
+  # Entry-level URL rewriting: map legacy URL shapes onto AISIX endpoints
+  # before routing. The first rule whose `match` regex matches the request
+  # path rewrites it (once, no cascading); the request then flows through
+  # the normal endpoint — auth, ACL, quota — as if the client had sent the
+  # rewritten path. `rewrite` replaces the matched portion of the path
+  # ($1/${name} expand capture groups); the query string is preserved. An
+  # invalid regex fails startup. Example: serve per-server MCP URLs like
+  # /mcp-servers/github/mcp on the /mcp/{server} endpoint.
+  # url_rewrites:
+  #   - name: per-server-mcp-compat
+  #     match: "^/mcp-servers/([^/]+)/mcp$"
+  #     rewrite: "/mcp/$1"
 
 admin:
   addr: "127.0.0.1:3001"

config.managed.yaml

@@ -44,6 +44,14 @@ proxy:
   # 0 = no request-body cap (the default); set a value to bound
   # per-request memory.
   # request_body_limit_bytes: 0
+  # Entry-level URL rewriting (first matching rule wins; `rewrite`
+  # replaces the matched portion of the path, $1 = capture group; the
+  # query string is preserved). Lets clients keep legacy URL shapes,
+  # e.g. per-server MCP paths served on the /mcp/{server} endpoint.
+  # url_rewrites:
+  #   - name: per-server-mcp-compat
+  #     match: "^/mcp-servers/([^/]+)/mcp$"
+  #     rewrite: "/mcp/$1"
 
 admin:
   # Bind to an unbindable port so even if managed mode somehow

crates/aisix-admin/src/playground_handler.rs

@@ -79,6 +79,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-core/Cargo.toml

@@ -17,6 +17,7 @@ thiserror.workspace = true
 anyhow.workspace = true
 config.workspace = true
 jsonschema.workspace = true
+regex.workspace = true
 schemars = { workspace = true, features = ["chrono"] }
 # ApiKey::expires_at parses RFC 3339 timestamps for key-expiry
 # enforcement in the proxy auth path (#933).

crates/aisix-core/src/config.rs

@@ -393,6 +393,16 @@ pub struct ProxyConfig {
     /// an L7 LB / ingress that sets `x-forwarded-for`.
     #[serde(default)]
     pub real_ip: RealIpConfig,
+    /// Entry-level URL rewrite rules, applied to every proxy-listener
+    /// request **before** routing (the admin and metrics listeners are
+    /// unaffected). The first rule whose `match` regex matches the request
+    /// path rewrites it — once, no cascading — and the request then flows
+    /// through the normal endpoint (auth, ACL, quota, …) as if the client
+    /// had sent the rewritten path. Lets operators map legacy URL shapes
+    /// onto AISIX endpoints, e.g. per-server MCP paths onto
+    /// `/mcp/{server}`. Empty (the default) = no rewriting.
+    #[serde(default)]
+    pub url_rewrites: Vec<UrlRewriteRule>,
 }
 
 impl ProxyConfig {
@@ -401,6 +411,26 @@ impl ProxyConfig {
     }
 }
 
+/// One entry-level URL rewrite rule (see [`ProxyConfig::url_rewrites`]).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UrlRewriteRule {
+    /// Optional name, used in logs when the rule fires.
+    #[serde(default)]
+    pub name: Option<String>,
+    /// Regex matched against the request path (never the query string).
+    /// Anchor with `^`/`$` to match the whole path; an unanchored pattern
+    /// matches anywhere in it.
+    #[serde(rename = "match")]
+    pub pattern: String,
+    /// Replacement for the matched portion of the path. Capture groups are
+    /// available as `$1`… / `${name}`; use `${1}x` (braced) when a literal
+    /// character follows a group reference. The query string is preserved
+    /// as sent.
+    #[serde(rename = "rewrite")]
+    pub replacement: String,
+}
+
 /// nginx `set_real_ip_from` + `real_ip_recursive` equivalent. Resolves
 /// the downstream client IP for usage logs (#492) from a forwarded
 /// header, trusting only addresses inside `trusted_proxies`.
@@ -1094,6 +1124,20 @@ impl Config {
     }
 
     fn validate(&self) -> Result<(), BootstrapError> {
+        // Fail fast on a rewrite rule that can never compile: it would
+        // otherwise surface as every legacy-path request 404ing, which is
+        // much harder to trace back to a typo in one regex.
+        for (i, rule) in self.proxy.url_rewrites.iter().enumerate() {
+            if let Err(e) = regex::Regex::new(&rule.pattern) {
+                let ctx = rule
+                    .name
+                    .clone()
+                    .unwrap_or_else(|| format!("proxy.url_rewrites[{i}]"));
+                return Err(BootstrapError::Config(format!(
+                    "{ctx}: invalid match regex: {e}"
+                )));
+            }
+        }
         if let Some(path) = self.resources_file.as_deref() {
             // File source selected: exactly one resource source may be
             // active. A configured etcd endpoint list alongside the file
@@ -1306,6 +1350,50 @@ admin:
         assert!(nets.iter().any(|n| n.to_string() == "10.0.0.0/8"));
     }
 
+    #[test]
+    fn loads_url_rewrites_and_rejects_an_invalid_regex() {
+        let f = write_yaml(
+            r#"
+etcd:
+  endpoints: ["http://127.0.0.1:2379"]
+  prefix: "/aisix"
+proxy:
+  addr: "0.0.0.0:3000"
+  url_rewrites:
+    - name: per-server-mcp-compat
+      match: "^/mcp-servers/([^/]+)/mcp$"
+      rewrite: "/mcp/$1"
+admin:
+  addr: "127.0.0.1:3001"
+  admin_keys: ["k1"]
+"#,
+        );
+        let cfg = Config::load_from_path(Some(f.path())).unwrap();
+        assert_eq!(cfg.proxy.url_rewrites.len(), 1);
+        assert_eq!(cfg.proxy.url_rewrites[0].replacement, "/mcp/$1");
+
+        let f = write_yaml(
+            r#"
+etcd:
+  endpoints: ["http://127.0.0.1:2379"]
+  prefix: "/aisix"
+proxy:
+  addr: "0.0.0.0:3000"
+  url_rewrites:
+    - match: "^/mcp-servers/([^/+/mcp$"
+      rewrite: "/mcp/$1"
+admin:
+  addr: "127.0.0.1:3001"
+  admin_keys: ["k1"]
+"#,
+        );
+        let err = Config::load_from_path(Some(f.path())).unwrap_err();
+        assert!(
+            format!("{err}").contains("url_rewrites"),
+            "error should name the bad rule: {err}"
+        );
+    }
+
     #[test]
     fn rejects_malformed_trusted_proxy_cidr() {
         let f = write_yaml(

crates/aisix-core/src/lib.rs

@@ -30,7 +30,7 @@ pub mod wildcard;
 pub use config::{
     AdminConfig, CacheBackend, CacheConfig, ClientTypeRule, Config, EtcdConfig, EtcdTlsConfig,
     HistogramBucketsConfig, ManagedConfig, ObservabilityConfig, ProxyConfig, RateLimitBackend,
-    RateLimitConfig, RealIpConfig, RedisConnConfig, RedisMode, TlsConfig,
+    RateLimitConfig, RealIpConfig, RedisConnConfig, RedisMode, TlsConfig, UrlRewriteRule,
 };
 pub use config_status::{
     hash_bytes, hash_entries, AppliedSnapshot, ConfigMetricsView, ConfigState, ConfigStatus,

crates/aisix-proxy/Cargo.toml

@@ -42,6 +42,7 @@ tower.workspace = true
 tower-http.workspace = true
 http-body-util.workspace = true
 bytes.workspace = true
+regex.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 # Token-estimation fallback for usage telemetry (token_estimate.rs).

crates/aisix-proxy/src/a2a.rs

@@ -375,6 +375,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/audio.rs

@@ -1439,6 +1439,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 10_485_760, // 10 MB for audio
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/completions.rs

@@ -744,6 +744,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/count_tokens.rs

@@ -544,6 +544,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/embeddings.rs

@@ -669,6 +669,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/images.rs

@@ -541,6 +541,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/jobs.rs

@@ -1802,6 +1802,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/lib.rs

@@ -60,6 +60,7 @@ mod request_id;
 mod rerank;
 mod responses;
 mod responses_bridge;
+mod rewrite;
 mod routing;
 mod semantic;
 pub mod sse_keepalive;
@@ -100,7 +101,7 @@ static SERVER_HEADER_VALUE: std::sync::LazyLock<HeaderValue> = std::sync::LazyLo
 /// OpenAI-compatible proxy surface.
 pub fn build_router(state: ProxyState) -> Router {
     let body_limit = state.request_body_limit_bytes;
-    Router::new()
+    let router = Router::new()
         .route("/livez", get(livez))
         .route("/readyz", get(readyz))
         .route("/v1/models", get(models::list_models))
@@ -220,13 +221,32 @@ pub fn build_router(state: ProxyState) -> Router {
             header::SERVER,
             SERVER_HEADER_VALUE.clone(),
         ))
+        // Rewrite the request path per `proxy.url_rewrites` before route
         // Outermost: mint the request id into the request extensions
         // before any handler/extractor runs, and stamp it onto every
         // response (including the short-circuited 4xx from the layers
         // above) so the whole proxy family carries `x-aisix-request-id`
         // and it equals the telemetry request_id. See request_id.rs.
         .layer(middleware::from_fn(request_id::ensure_request_id))
-        .with_state(state)
+        .with_state(state.clone());
+
+    if state.url_rewrites.is_empty() {
+        return router;
+    }
+    // Pre-routing URL rewriting (`proxy.url_rewrites`). `Router::layer`
+    // middleware runs AFTER route matching, so a URI rewritten there could
+    // never change which route matches. Wrapping the whole router as the
+    // fallback of an outer router — whose "routing" trivially resolves to
+    // that fallback — gives the rewrite layer a genuine pre-routing seat:
+    // it mutates the URI, then the inner router matches on the rewritten
+    // path. Built only when rules are configured, so the default path pays
+    // nothing. See rewrite.rs.
+    Router::new()
+        .fallback_service(router)
+        .layer(middleware::from_fn_with_state(
+            state,
+            rewrite::rewrite_request_uri,
+        ))
 }
 
 async fn record_in_flight_request(
@@ -651,6 +671,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }
@@ -1624,6 +1645,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: limit,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         };
         ProxyState::new(handle, hub, &cfg).without_cache()

crates/aisix-proxy/src/mcp.rs

@@ -546,6 +546,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/messages.rs

@@ -3578,6 +3578,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/models.rs

@@ -119,6 +119,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/passthrough.rs

@@ -894,6 +894,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/realtime.rs

@@ -799,6 +799,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/rerank.rs

@@ -735,6 +735,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }

crates/aisix-proxy/src/responses.rs

@@ -3065,6 +3065,7 @@ mod tests {
             addr: "127.0.0.1:0".into(),
             request_body_limit_bytes: 1_048_576,
             real_ip: Default::default(),
+            url_rewrites: Vec::new(),
             tls: None,
         }
     }