Skip to main content
Version: 1.11.0

Upstream Authentication

Each registered MCP server can define how AISIX authenticates to the upstream server. AISIX holds any upstream credential gateway-side and presents it when listing tools or forwarding a tool call. The caller API key an MCP client sends to AISIX authenticates the caller to AISIX, and by default no caller header reaches the upstream server. A server that must see one — including the caller's own credential — opts in with forward_client_headers.

Three modes act on the caller's behalf instead of using a gateway credential. oauth_delegate relays a caller-supplied upstream token. oauth2_token_exchange exchanges the caller's Microsoft Entra ID token. oauth2_authorization_code lets each user sign in to the upstream and calls it with that user's token.

Set the credential with the auth_type field and the fields required by that authentication mode. The same modes are available through the control-plane path for AISIX Enterprise and AISIX Cloud and the resources-file path for AISIX OSS.

Prerequisites​

Before starting, prepare the following:

  • For AISIX Enterprise or AISIX Cloud, an environment. Dashboard users need permission to create and update MCP servers. Admin API users need a write-scoped token from an identity with the same MCP-server permissions. For AISIX Enterprise, follow the AISIX Enterprise getting-started guide. To request AISIX Cloud access, contact API7.
  • Complete Set Up MCP Gateway for AISIX Enterprise, AISIX Cloud, or the open-source AISIX gateway. To run the optional end-to-end verification, keep the same shell, gateway, Everything test server, and temporary Docker network running.
  • cURL for the request examples.

Authentication Modes​

Choose the mode that matches how the upstream MCP server expects AISIX to authenticate:

auth_typeUpstream credentialHow AISIX presents it
noneNoneNo credential is sent.
bearerBearer token in secretAuthorization: Bearer <secret>
api_keyAPI key in secretx-api-key: <secret>
oauth2client_id + token_url + secretAISIX obtains an access token, then sends Authorization: Bearer <access_token>.
oauth_delegateNoneAISIX relays the caller's own Authorization header unchanged. See Delegate the Caller's Token.
oauth2_token_exchangetoken_exchange_profile + client_id + token_url + secret + scopesAISIX exchanges the caller's verified JWT for an access token, then sends Authorization: Bearer <access_token>. See Entra On-Behalf-Of Token Exchange.
oauth2_authorization_codeAll optional: client_id, secret, token_url, scopes, authorization_url, registration_urlEach user signs in to the upstream, and AISIX sends Authorization: Bearer <that user's access token>. type: mcp only. See Interactive MCP Sign-In.

The secret holds the plaintext credential AISIX presents upstream, or the client secret AISIX authenticates to the token endpoint with. It is used only gateway-side and is never sent to the calling client. To rotate a credential, update the resource with a new secret.

Use HTTPS for a credentialed upstream. When a bearer token, API key, or OAuth credential is configured on an http:// URL, the gateway logs a warning because the credential crosses the network in plaintext. For OAuth, the gateway also warns when token_url uses http:// because the client secret is sent to that endpoint.

Configure Upstream Authentication​

Configure upstream authentication using the management path for your deployment.

  1. Open MCP servers and select New MCP server.
  2. Keep MCP server under Server type, then enter the server Name and URL.
  3. Under Available in environments, select the target environment.
  4. Choose the mode under Authentication. The form shows the fields required by that mode.
  5. For a static bearer credential, select Bearer token, enter the token, and select Register MCP server.

The same form offers None, API key, OAuth 2.0 (client credentials), Delegate caller token, Token exchange (Entra OBO), and OAuth 2.0 (per-user sign-in).

New OpenAPI-backed MCP server form with API key authentication selected

To rotate or clear authentication:

  1. Select Edit on the server.
  2. Keep a stored credential blank to retain it, or enter a new value to rotate it.
  3. Select Save.

Switching to another type that requires a secret requires a fresh value. Switching to a mode with no stored credential clears it. Per-user sign-in provides Remove the stored client secret separately.

Credential Handling​

AISIX validates credential fields against auth_type when you create or update a server. A server with invalid credential fields is rejected at write time.

If a credential later stops working, such as after a secret is rotated or revoked, only that server's tools become unavailable. tools/list omits that server's tools, while a direct permitted call returns a generic JSON-RPC internal error. Other registered MCP servers keep working. AISIX logs the detailed failure and does not expose credential details to the calling agent.

Forward Caller Headers to an Upstream Server​

The credential above belongs to the gateway. An internal server that authorizes the end user instead needs the caller's own header. Configure forward_client_headers with header-name patterns to relay it. The empty-by-default field applies to type: mcp and type: openapi, so a REST API exposed as tools receives matching headers on every tool call.

  1. Select Edit on the server and expand Advanced.
  2. Under Forward client headers, enter one exact name or single-* pattern per line.
  3. Select Save.

To stop forwarding caller headers, clear the field and save the server again.

Each entry is an exact header name or a name with a single * wildcard, matched case-insensitively. A forwarded header reaches the server whatever AISIX would otherwise have done with it.

Apply these matching and replacement rules:

Header caseBehavior
Gateway credential slotAn exact match replaces the gateway's credential with the caller's value; AISIX never sends both. authorization is the bearer and OAuth slot. API-key authentication uses api_key_header, which defaults to x-api-key.
Delegate, token-exchange, or per-user sign-in serveroauth_delegate, oauth2_token_exchange, and oauth2_authorization_code own authorization, so adding it to forward_client_headers has no effect.
Protected credential or trace headerCredential slots, traceparent, tracestate, and AWS SigV4 headers require an exact name. Globs such as * or x-* do not match them.
Custom api_key_headerExact-name protection does not cover a custom header automatically. A matching glob can let the caller replace the configured upstream credential.
MCP session headermcp-session-id, mcp-protocol-version, and last-event-id are never forwarded because AISIX opens a separate upstream session.

Caller Headers AISIX Never Forwards lists the other protected headers, including host, hop-by-hop headers, the x-aisix-* namespace, and body metadata AISIX regenerates.

Delegate the Caller's Token​

Use oauth_delegate when the upstream server authorizes each end user with its own OAuth tokens, and the client already holds such a token. AISIX stores no credential for the server. It relays the caller's Authorization header to the upstream unchanged.

The caller therefore sends two credentials: its gateway key in x-aisix-api-key, and its token for the upstream in Authorization. AISIX relays Authorization only when the gateway key arrived in x-aisix-api-key. An Authorization header that carried the gateway key itself is never sent upstream. When the caller sends no upstream token, AISIX calls the server without credentials and the server's own response decides the outcome. AISIX does not obtain the upstream token for the client; the client gets it from the upstream's authorization server.

oauth_delegate applies to type: mcp and type: openapi servers. No forward_client_headers entry is needed.

Configure a Delegate Server​

  1. Open MCP servers and create or edit the server.
  2. Under Authentication, choose Delegate caller token. This mode has no credential inputs.
  3. Save the server.

Which Servers Receive the Token​

The caller's token reaches only the servers its MCP access rules reach. A delegate server outside the caller's tool access grant is contacted without it.

On /mcp/{server}, only that server receives the token. On the aggregated /mcp, the caller sends a single Authorization header, and AISIX relays that same token to every delegate server the caller's grant reaches. When different delegate servers need different tokens, connect the client to each server's /mcp/{server} entry instead of the aggregated endpoint.

Connect a Client​

The client sets both headers on every request. For example, a Claude Code project can declare the server in .mcp.json, with both values taken from the environment:

.mcp.json
{
"mcpServers": {
"runbooks": {
"type": "http",
"url": "https://gateway.example.com/mcp/runbooks",
"headers": {
"x-aisix-api-key": "${AISIX_MCP_KEY}",
"Authorization": "Bearer ${RUNBOOKS_TOKEN}"
}
}
}
}

Replace https://gateway.example.com with the gateway's proxy URL. Claude Code expands ${VAR} in headers from its environment. See the Claude Code MCP documentation for the configuration scopes and other variable rules.

To check the server with cURL:

curl -sS -X POST "$AISIX_PROXY/mcp/runbooks" \
-H "x-aisix-api-key: $AISIX_MCP_KEY" \
-H "Authorization: Bearer $RUNBOOKS_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

x-aisix-api-key itself is never forwarded upstream. See Send the Gateway Key in x-aisix-api-key for how AISIX reads it.

Optional: Verify with a Local Test Proxy​

The configuration above defines the credential AISIX should send, but the Everything server from the setup guide accepts requests without authenticating them. It therefore cannot prove that the gateway presented the expected token. For an end-to-end local check, put a small bearer-authenticated reverse proxy in front of the server and verify both accepted and rejected requests.

The proxy is for local testing only: it uses plain HTTP and removes the bearer token before forwarding an accepted request to the Everything server.

The helper below contains the local proxy setup. Copy it as-is; the remaining steps configure and test AISIX.

Start the local bearer-checking proxy

Export a distinct upstream token, then define and start the test proxy on the existing Docker network:

export MCP_UPSTREAM_TOKEN="mcp-upstream-test-token"

start_mcp_auth_proxy() {
docker rm -f aisix-mcp-auth >/dev/null 2>&1 || true
docker run -d --name aisix-mcp-auth \
--network aisix-mcp \
-e UPSTREAM_TOKEN="$1" \
caddy:2.11.4-alpine \
sh -c 'caddy run --config /dev/stdin --adapter caddyfile <<EOF
:3002 {
@authorized header Authorization "Bearer $UPSTREAM_TOKEN"
handle @authorized {
reverse_proxy aisix-mcp-everything:3001 {
header_up -Authorization
header_up Host {upstream_hostport}
}
}
handle {
respond "upstream authentication failed" 401
}
}
EOF'

for attempt in $(seq 1 30); do
docker logs aisix-mcp-auth 2>&1 |
grep -q "serving initial configuration" && return
sleep 1
done
docker logs aisix-mcp-auth >&2
return 1
}

start_mcp_auth_proxy "$MCP_UPSTREAM_TOKEN"

Configure AISIX to Use the Proxy​

Update the existing everything server to use http://aisix-mcp-auth:3002/mcp, auth_type: bearer, and MCP_UPSTREAM_TOKEN as its secret. This address works when the AISIX gateway container can join the local aisix-mcp network, whether it connects to Enterprise, Cloud, or no control plane. For a managed gateway elsewhere, deploy an equivalent authenticated proxy at an HTTPS endpoint the gateway can reach and use that URL instead. This guide's OSS verifier assumes the Docker quickstart topology.

  1. Open MCP servers and select Edit on everything.
  2. Change URL to http://aisix-mcp-auth:3002/mcp.
  3. Under Authentication, select Bearer token and enter the value of MCP_UPSTREAM_TOKEN.
  4. Select Save.

Verify a Valid Credential​

After the control plane projects the update or the open-source AISIX gateway restarts, call the permitted tool:

MCP_RESPONSE=$(curl -fsS -X POST "$AISIX_PROXY/mcp" \
-H "Authorization: Bearer $AISIX_MCP_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 10,
"method": "tools/call",
"params": {
"name": "everything__echo",
"arguments": {"message": "authenticated through AISIX"}
}
}')

echo "$MCP_RESPONSE" | jq -e \
'.result.content[] | select(.text == "Echo: authenticated through AISIX")'

The command prints the matching result. The proxy accepts a request only when it carries the gateway-held token, so this response confirms that AISIX replaced the caller's Authorization header with the upstream credential. The proxy removes that credential before forwarding to the Everything server.

Verify a Rejected Credential​

Make the proxy expect a different token without changing the credential in AISIX:

start_mcp_auth_proxy "deliberately-wrong-token"

MCP_FAILURE=$(curl -fsS -X POST "$AISIX_PROXY/mcp" \
-H "Authorization: Bearer $AISIX_MCP_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 11,
"method": "tools/call",
"params": {
"name": "everything__echo",
"arguments": {"message": "this call should fail"}
}
}')

echo "$MCP_FAILURE" | jq -e \
'.error.code == -32603 and
.error.message == "upstream MCP server '\''everything'\'' failed to call tool"'

if echo "$MCP_FAILURE" | grep -qF "$MCP_UPSTREAM_TOKEN" || \
echo "$MCP_FAILURE" | grep -qF "$AISIX_MCP_KEY"; then
echo "credential found in client response" >&2
exit 1
fi

The jq command prints true, and the credential check produces no output. This upstream-authentication failure uses HTTP 200, so inspect the JSON-RPC error object rather than the HTTP status. A failed upstream also contributes no tools to tools/list; other reachable servers still contribute theirs.

Restore the expected token before continuing:

start_mcp_auth_proxy "$MCP_UPSTREAM_TOKEN"

Keep aisix-mcp-auth running while you use this authenticated local setup. Remove it before running the cleanup commands in the setup guide:

docker rm -f aisix-mcp-auth

Next Steps​

You now understand how AISIX authenticates to upstream MCP servers. Use these guides to control which callers can reach those tools and how their traffic is governed:

  • Control tool access: scope caller API keys to specific tools, whole servers, or every tool.
  • Rate limits and budgets: apply request and concurrency limits, and configure budgets for MCP tool calls.
  • Guardrails: inspect MCP tool arguments and results.
  • Upstream request headers: the same forward_client_headers field on the other faces AISIX proxies through, and the full list of headers no pattern can reach.