Product Documentation
ADC
14.1-Current Release 13.1
View PDF

NetScaler as an MCP Gateway

June 18, 2026
Contributed by: 
C

NetScaler® is deployed as a centralized MCP Gateway in either forward-proxy (client-side) or reverse-proxy (server-side) mode. By directing clients to a single NetScaler virtual IP (VIP) address rather than multiple individual endpoints, routing, and backend management are fully consolidated.

Using content switching and load balancing, NetScaler intercepts traffic from a single client-facing endpoint and dynamically routes requests to the appropriate backend MCP server based on the x-netscaler-mcp-server header. This architecture simplifies client integration, ensures consistent policy enforcement, and allows you to apply uniform operational controls, such as traffic monitoring, session persistence, and rate limiting, across all MCP traffic.

MCP architecture

Understanding the MCP profile

The MCP profile is a configuration entity designed to standardize MCP backend integration. It provides a centralized mechanism to handle authentication, header injection, and protocol-specific transformations required for MCP traffic, eliminating the need for complex rewrite policies and custom configurations.

By abstracting backend-specific requirements such as token management, host and URL rewriting, and deployment mode handling, the MCP profile enables consistent and scalable MCP Gateway deployments.

The following parameters control the behavior across different deployment and authentication scenarios:

Parameter Values Default Description
-comment <string> – Optional description for the MCP profile.
-insertHeaderInClientRequest ENABLED / DISABLED DISABLED Inserts an authorization header (token) into requests sent to the backend MCP server.
-mcpProtocolVersion <string> – Specifies the MCP protocol version used in communication.
-mcpTokenOrApi <token> – Token (PAT/API key) used for backend authentication.
-proxyMode FORWARD / REVERSE FORWARD Defines the deployment model of the NetScaler MCP Gateway.
-hostReplacement ENABLED / DISABLED ENABLED Rewrites the host header to match the backend MCP server FQDN.
-urlReplacement ENABLED / DISABLED ENABLED Rewrites the request URL or path for backend compatibility.
-mcpCounterStatistics ENABLED / DISABLED ENABLED Enables MCP-specific statistics counters.
-mcpprofileType FRONTEND / BACKEND BACKEND Defines whether the profile is applied at the front end or the back end.

Points to note

  • In forward-proxy mode, client requests are sent to a single gateway URL, and NetScaler routes traffic to different backend MCP servers based on a custom header.
  • Session stickiness is required for stateful MCP servers. Subsequent requests for a session must reach the same backend server to avoid session-not-found errors.
  • If backend MCP servers expect a specific host header and backend URL path, use MCP profile host or URL replacement, or equivalent rewrite policies.

Use case

This feature can be used to expose a single MCP endpoint for clients while routing requests to multiple backend MCP servers based on a target-server header.

Prerequisites

Ensure that the following requirements are met:

  • Deploy a content switching virtual server to act as the primary MCP Gateway entry point.
  • Create load balancing virtual servers or services for backend MCP servers and verify that their FQDNs and paths are reachable.
  • Configure clients to send the target backend identifier using the x-netscaler-target-mcp-server header.
  • Set up token insertion in the MCP profile, or ensure clients pass tokens using the X-Netscaler-Backend-Auth-Token header.
  • Verify administrative privileges to create and bind content switching, load balancing, rewrite, responder, and authentication configurations.

Configure NetScaler as an MCP Gateway

The following sample configuration shows how to deploy NetScaler as an MCP Gateway using content switching and load balancing through header-based routing and optional request or response rewrites.

A. Configure a content switching gateway virtual server

Create a content switching virtual server as the single MCP Gateway endpoint and bind routing policies that select a backend based on the MCP server header.

add cs vserver cs1 SSL <IP address> 80 -cltTimeout 180 -persistenceType NONE

add lb vserver lb_app1_mcp SSL 0.0.0.0 0
add lb vserver lb_app2_mcp SSL 0.0.0.0 0

add serviceGroup sg_app1 SSL
bind serviceGroup sg_app1 <server_ip> 443
bind lb vserver lb_app1_mcp sg_app1

add serviceGroup sg_app2 SSL
bind serviceGroup sg_app2 <server_ip> 443
bind lb vserver lb_app2_mcp sg_app2

add cs action cs_act_app1 -targetLBVserver lb_app1_mcp
add cs action cs_act_app2 -targetLBVserver lb_app2_mcp

add cs policy new-pol-app1 -rule "HTTP.REQ.HEADER(\"x-netscaler-target-mcp-server\").BEFORE_STR(\"/\").CONTAINS(\"app1.com\")" -action cs_act_app1
add cs policy new-pol-app2 -rule "HTTP.REQ.HEADER(\"x-netscaler-target-mcp-server\").BEFORE_STR(\"/\").CONTAINS(\"app2.com\")" -action cs_act_app2

bind cs vserver cs1 -policyName new-pol-app1 -priority 10
bind cs vserver cs1 -policyName new-pol-app2 -priority 15
<!--NeedCopy-->

B. Optional response-side rewrites for authentication flows

If the backend server returns a WWW-Authenticate challenge containing resource metadata, apply response-side rewrites so that the client continues to interact safely through the gateway.

Note:

This section is applicable only if NetScaler is not acting as an authentication proxy and the backend server requires a per-user authentication token. For a service-level PAT, the token is configured directly on the MCP profile without the following rewrite policies.

add rewrite action resp_act1 replace q{http.res.header("www-authenticate").After_str("resource_metadata=\"").before_str(":/")} "\"http\""
add rewrite action resp_act replace q{http.res.header("www-authenticate").After_str("resource_metadata=\"https://").before_str("/")} http.req.hostname

add rewrite action rw_act1 replace_all "HTTP.RES.BODY(10000)" q{CLIENT.SSL.IS_SSL.IF(",\"resource\":\"https://" + http.req.hostname + "/mcp\"", ",\"resource\":\"http://" + http.req.hostname + "/mcp\"")} -search "xpath_json(xp%/resource%)"

add rewrite policy rw_pol2 "http.req.url.eq(\"/mcp\") && CLIENT.SSL.IS_SSL.NOT" resp_act1
add rewrite policy rw_pol1 true resp_act
add rewrite policy rw_pol3 true rw_act1

# Bind the response-side rewrite policies to the backend LB vserver (example shown for App1 vserver)
bind lb vserver lb_app1_mcp -policyName rw_pol2 -priority 6 -gotoPriorityExpression next -type RESPONSE
bind lb vserver lb_app1_mcp -policyName rw_pol1 -priority 7 -gotoPriorityExpression next -type RESPONSE
bind lb vserver lb_app1_mcp -policyName rw_pol3 -priority 8 -gotoPriorityExpression next -type RESPONSE
<!--NeedCopy-->

C. Use the MCP profile to reduce rewrite overhead

Enable hostReplacement and urlReplacement in the MCP profile and bind it to the backend service or service group to eliminate complex manual rewrites.

add mcpprofile m1 -hostReplacement ENABLED -urlReplacement ENABLED
set service mcp -mcpProfileName m1
set servicegroup sg1 -mcpProfileName m1
<!--NeedCopy-->

D. Sample client configuration

Configure the MCP client to point to the NetScaler Gateway URL and provide the target backend MCP server inside the custom header block.

{
  "servers": {
     "proxy-server": {
        "url": "https://proxy.aaanetscaler.local/mcp",
        "type": "http",
        "headers": {
          "x-netscaler-target-mcp-server": "api.githubcopilot.com/mcp/",
          "X-MCP-TOOLSETS": "all"
        }
     }
  },
  "inputs": []
}
<!--NeedCopy-->

Troubleshooting

Routing goes to the wrong backend MCP server

Cause: The header value does not match content switching policy rules (domain or prefix).

Workaround: Verify the client header (x-netscaler-mcp-server) and content switching policy expressions.

Backend MCP server returns session errors

Cause: Stateful MCP servers require stickiness. Requests for the same session must land on the same backend.

Workaround: Ensure session ID-based persistence is configured and validate by repeating tool calls.

Authentication challenges redirect clients away from the gateway

Cause: WWW-Authenticate resource metadata points to backend URLs.

Workaround: Apply response-side rewrite policies for resource metadata and payload replacement.

NetScaler as an MCP Gateway
June 18, 2026
Contributed by: 
C
June 18, 2026
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.