Scenarios
By default, an MCP service exposes only one fixed access endpoint. All requests are uniformly forwarded to the same backend, making it impossible to perform differentiated distribution based on request sources. With MCP service routing, you can configure multiple routing rules under the same MCP service to match inbound requests based on Path, HTTP method, and Header (including Host) conditions, enabling scenarios such as multi-tenant isolation, multi-environment parallelism, and canary traffic distribution.
Typical scenarios:
Multi-environment parallelism: The same MCP service supports both the production domain mcp-prod.example.com and the test domain mcp-test.example.com simultaneously.
Multi-tenant isolation: Distribute traffic from different tenants to separate endpoints based on the Host or X-Tenant-Id Header.
Canary traffic distribution: Requests carrying X-Canary: true are routed through a separate route.
Version routing: Match based on the regular expression pattern of X-Version (for example, ^v[2-3]\\..*).
Note:
All routing rules share the same backend service (Upstream). Routing rules only control which requests can enter, not where they are forwarded to. To change the backend, edit the MCP service itself.
Prerequisites
A Cloud Native Gateway instance of the AI Gateway type has been created, and its status is Running.
The gateway data plane version must be 3.9.5 or later.
An MCP service has been created under this instance (both standard MCP services and HTTP-to-MCP services are supported).
Definitions
|
Default Route | A route automatically generated by the system when an MCP service is created. Its name is fixed as default and its priority is 0. It cannot be modified, deleted, or disabled, serving as a fallback entry to ensure service reachability. |
Custom Routing | A routing rule manually created by users. Its priority starts from 1000 by default. It can be created, deleted, modified, queried, enabled, or disabled. |
Matching Expression | A route matching expression automatically generated by the system based on the Path, Methods, and Header conditions you configure. It is read-only and does not need to be manually written. |
Operation Steps
Viewing the Route List
2. In the left sidebar, choose Instance List, and click the target AI Gateway instance ID to go to the instance details page.
3. Select MCP Management, and click the target MCP service name to go to the details page.
4. Select the Routing Rules tab to view related information.
|
Priority | 0. A larger value indicates a higher matching priority. The default route is 0. |
Route Name | The default route is fixed as default and carries the Default tag. |
Status | Enabled / Disabled |
Matching Path | Path value + matching method tag (Exact/Prefix/Regex) |
Host Matching | No limit |
Path Matching | Exact match, /mcpservers/mcp service name/mcp |
Header Matching | Display unconditionally. |
HTTP Method | List of allowed methods |
Creation Time | Creation time of the route |
Operation | Edit / Enable/Disable / Delete (no action buttons for the default route row) |
Creating a Route
1. On the Routing Rules tab, click Add Rule.
2. In the dialog box, configure the following:
Basic information:
|
Route Name | Required | Up to 64 characters | It must be unique within the same MCP service. Do not use default (system-reserved). |
Priority | Optional. | Default: 1000 | A larger value indicates a higher matching priority. Custom routes are recommended to maintain a value greater than or equal to 1000 to ensure priority over the default route. |
Description | Optional. | Up to 200 characters | - |
Configure Path Matching:
|
Matching Path | Optional. | Up to 256 characters | Must start with /, for example, /api. Paths of different routes can be duplicated and distinguished by other conditions. |
Matching Method | Optional. | Exact / Prefix / Regex
| Exact: The path is exactly the same; Prefix: The path starts with the specified value; Regex: The path matches the RE2 regular expression.
|
Note:
The regular expression pattern must use valid RE2 syntax (for example, ^/api/v[0-9]+$). Invalid regular expressions are rejected upon submission.
Configure Host Matching.
|
Matching Method | Required | Exact / Prefix / Regex
| Regex must be valid RE2 syntax.
|
Match Value | Required | - | Enter the target Host value. |
Configure HTTP Method (new in this release):
|
HTTP Method | Optional. | GET / POST / PUT / DELETE / PATCH / HEAD / OPTIONS
| Multiple selection, used as a method allowlist. If no method is selected, no method is limited |
Configure Header Matching, and click Add Header Condition to add a row:
|
Header Name | Required | Up to 64 characters | Case-insensitive. When Host is entered, the system automatically identifies it as matching the request domain name (no separate Host configuration item is required). |
Matching Method | Required | Exact / Prefix / Regex
| Regex must be valid RE2 syntax.
|
Match Value | Required | Up to 256 characters | - |
Note:
Multiple Header conditions are combined using the AND relationship, meaning a match occurs only when all conditions are met.
A maximum of 8 Host and Header rules can be configured in total.
3. During configuration, the system checks in real time whether the set of matching conditions conflicts with existing routes under the same service. If a conflict occurs, the dialog box displays the name of the conflicting route, and you must adjust the conditions before submitting.
4. Click OK. The new route appears in the list with its status set to Enabled by default.
Modifying a Route
1. On the Routing Rules tab, click Edit in the operation column of the target route.
2. Modify the required parameters and click OK.
Note:
The <0>default route (<1>default</1>) cannot be modified.</2> No Edit button is displayed for this row.
Modifiable fields: route name, priority, match path and match method, HTTP method, Header match conditions, and description.
After modification, the system re-validates uniqueness. If the route still conflicts with other routes after excluding itself, the submission fails.
Enabling or Disabling a Route
1. On the Route Management tab, click Disable or Enable in the operation column of the target route.
2. In the confirmation dialog, click OK.
Note:
Disabled routes do not participate in traffic matching, but their configurations are retained and can be re-enabled at any time.
The default route cannot be disabled and remains enabled at all times.
Enable/disable operations are idempotent. Repeating the same state does not cause an error.
Delete Routing
1. On the Route Management tab, click Delete in the operation column of the target route.
2. In the confirmation dialog, click OK.
Note:
The default route cannot be deleted. No Delete button is displayed for this row.
When an MCP service is deleted, all custom routes under it are cleaned up in cascade, eliminating the need for individual deletion.
Deletion is irreversible. Confirm that the route no longer has traffic.
Related Instructions
Routing match rule
Within a single route, the matching path, HTTP method, and all Header conditions have an AND relationship. The route is matched only when all conditions are met.
Routes are sorted by priority, and routes with larger values are matched first.
Custom routes (priority greater than or equal to 1000) always take precedence over the default route (priority 0) in matching. When no custom route is matched, the request falls back to the default route, ensuring that the service remains reachable.
Only routes in the enabled state participate in matching.
For routes with the same priority, the data plane automatically scores and sorts them by the complexity of their match conditions, and routes with more specific conditions are matched first.