# 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`](#forward-caller-headers-to-an-upstream-server).

Three modes act on the caller's behalf instead of using a gateway credential. [`oauth_delegate`](#delegate-the-callers-token) relays a caller-supplied upstream token. [`oauth2_token_exchange`](https://docs.api7.ai/ai-gateway/mcp-gateway/entra-obo-token-exchange.md) exchanges the caller's Microsoft Entra ID token. [`oauth2_authorization_code`](https://docs.api7.ai/ai-gateway/mcp-gateway/interactive-sign-in.md) 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[​](#prerequisites "Direct link to 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](https://docs.api7.ai/ai-gateway/getting-started/aisix-cloud-quickstart.md). To request AISIX Cloud access, [contact API7](https://api7.ai/contact).
* Complete [Set Up MCP Gateway](https://docs.api7.ai/ai-gateway/mcp-gateway/setup.md) 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](https://curl.se/) for the request examples.

## Authentication Modes[​](#authentication-modes "Direct link to Authentication Modes")

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

| `auth_type`                 | Upstream credential                                                                                 | How AISIX presents it                                                                                                                                                                                                               |
| --------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none`                      | None                                                                                                | No credential is sent.                                                                                                                                                                                                              |
| `bearer`                    | Bearer token in `secret`                                                                            | `Authorization: Bearer <secret>`                                                                                                                                                                                                    |
| `api_key`                   | API key in `secret`                                                                                 | `x-api-key: <secret>`                                                                                                                                                                                                               |
| `oauth2`                    | `client_id` + `token_url` + `secret`                                                                | AISIX obtains an access token, then sends `Authorization: Bearer <access_token>`.                                                                                                                                                   |
| `oauth_delegate`            | None                                                                                                | AISIX relays the caller's own `Authorization` header unchanged. See [Delegate the Caller's Token](#delegate-the-callers-token).                                                                                                     |
| `oauth2_token_exchange`     | `token_exchange_profile` + `client_id` + `token_url` + `secret` + `scopes`                          | AISIX exchanges the caller's verified JWT for an access token, then sends `Authorization: Bearer <access_token>`. See [Entra On-Behalf-Of Token Exchange](https://docs.api7.ai/ai-gateway/mcp-gateway/entra-obo-token-exchange.md). |
| `oauth2_authorization_code` | All optional: `client_id`, `secret`, `token_url`, `scopes`, `authorization_url`, `registration_url` | Each user signs in to the upstream, and AISIX sends `Authorization: Bearer <that user's access token>`. `type: mcp` only. See [Interactive MCP Sign-In](https://docs.api7.ai/ai-gateway/mcp-gateway/interactive-sign-in.md).        |

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 "Direct link to Configure Upstream Authentication")

Configure upstream authentication using the management path for your deployment.

* AISIX Enterprise or Cloud
* AISIX OSS

- Dashboard
- Admin API

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](https://static.api7.ai/uploads/2026/11/20/RbcgYuPp_mcp-upstream-auth.webp)

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.

The AISIX Cloud Admin API creates the server and its upstream credential together. `allowed_environments` lists the environments that receive the server. A server with an empty or missing list is exposed to no environment, so every example below includes the target environment.

Export the control-plane connection values:

```
# AISIX_CP includes /api and has no trailing slash

# The local AISIX Enterprise quickstart uses http://localhost:8080/api

export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"

export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

export ENV_ID="YOUR_ENVIRONMENT_ID"
```

### No Authentication[​](#no-authentication "Direct link to No Authentication")

Use `none` when the upstream MCP server does not require a credential, such as a server reachable only on a trusted internal network.

The following example creates a server resource without an upstream credential:

```
curl -sS -X POST "$AISIX_CP/mcp_servers" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "runbooks",

    "url": "https://runbooks.internal/mcp",

    "auth_type": "none",

    "allowed_environments": ["'"$ENV_ID"'"]

  }'
```

`auth_type` defaults to `none`, so you can also omit it. Leave `secret`, `client_id`, `token_url`, and `scopes` unset for a `none` server.

### Bearer Token[​](#bearer-token "Direct link to Bearer Token")

Use `bearer` when the upstream server expects a static token in the `Authorization` header.

The following example creates a server resource with the bearer token AISIX should send upstream:

```
curl -sS -X POST "$AISIX_CP/mcp_servers" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "github",

    "url": "https://mcp.example.com/mcp",

    "auth_type": "bearer",

    "secret": "YOUR_UPSTREAM_MCP_TOKEN",

    "allowed_environments": ["'"$ENV_ID"'"]

  }'
```

❶ `bearer` sends `Authorization: Bearer <secret>` on every request to this upstream.

❷ `secret` is required and must be non-empty.

### API Key[​](#api-key "Direct link to API Key")

Use `api_key` when the upstream server expects a key in the `x-api-key` header.

The following example creates a server resource with the API key AISIX should send upstream:

```
curl -sS -X POST "$AISIX_CP/mcp_servers" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "catalog",

    "url": "https://catalog.example.com/mcp",

    "auth_type": "api_key",

    "secret": "YOUR_UPSTREAM_API_KEY",

    "allowed_environments": ["'"$ENV_ID"'"]

  }'
```

❶ `api_key` sends `x-api-key: <secret>` on every request to this upstream.

❷ `secret` is required and must be non-empty.

### OAuth 2.0 Client Credentials[​](#oauth-20-client-credentials "Direct link to OAuth 2.0 Client Credentials")

Use `oauth2` when the upstream server accepts OAuth 2.0 access tokens and you have machine-to-machine client credentials for it.

AISIX exchanges the client credentials at the token endpoint, sends the access token upstream, and reuses it until shortly before it expires. If the upstream server rejects a token as unauthorized, AISIX discards the cached token and obtains a fresh one on the next call.

The following example creates a server resource with the OAuth client credentials AISIX should use for this upstream:

```
curl -sS -X POST "$AISIX_CP/mcp_servers" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "orders",

    "url": "https://orders.example.com/mcp",

    "auth_type": "oauth2",

    "client_id": "aisix-gateway",

    "token_url": "https://auth.example.com/oauth/token",

    "secret": "YOUR_OAUTH_CLIENT_SECRET",

    "scopes": ["mcp.read", "mcp.write"],

    "allowed_environments": ["'"$ENV_ID"'"]

  }'
```

❶ `oauth2` uses the OAuth 2.0 client credentials grant for this upstream.

❷ `client_id`, `token_url`, and `secret` are required for an `oauth2` server.

❸ `scopes` is optional. AISIX joins the values with spaces into the token request's `scope` parameter.

AISIX keeps the access token gateway-side and never returns it to the caller.

Add this authenticated `github` entry to `mcp_servers`; replace it if that name already exists. Keep the other resources unchanged, and supply the secret through environment interpolation:

resources.yaml (MCP server authentication)

```
mcp_servers:

  - id: 631940a7-bdb5-4d67-9ffd-74798b91df52

    name: github

    type: mcp

    url: https://mcp.example.com/mcp

    auth_type: bearer

    secret: ${GITHUB_MCP_TOKEN}
```

Set `GITHUB_MCP_TOKEN` in the gateway process environment. For `none`, omit `secret`. For `api_key`, the same `secret` field is sent as `x-api-key`. For `oauth2`, add `client_id`, `token_url`, and `secret`, with optional `scopes`. For `oauth_delegate`, omit `secret`; for `oauth2_token_exchange`, see [Entra On-Behalf-Of Token Exchange](https://docs.api7.ai/ai-gateway/mcp-gateway/entra-obo-token-exchange.md#register-the-mcp-server).

Environment variables belong to the gateway process. A running process cannot receive a variable that you add or change in the host shell. After adding or rotating an environment-supplied credential, validate the resources file with the new value and restart the process. For a container, recreate it with the new environment value. Use a reload only when the resource file changes and the running process already has every referenced variable with the intended value.

If validation or reload fails, the gateway never applies the invalid entry; on reload it keeps serving the last valid configuration. See the [CLI Reference](https://docs.api7.ai/ai-gateway/reference/cli.md#validate-a-resources-file) and [Configuration Status](https://docs.api7.ai/ai-gateway/reference/config-status.md).

## Credential Handling[​](#credential-handling "Direct link to 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[​](#forward-caller-headers-to-an-upstream-server "Direct link to 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](https://docs.api7.ai/ai-gateway/mcp-gateway/openapi-servers.md) receives matching headers on every tool call.

* AISIX Enterprise or Cloud
* AISIX OSS

- Dashboard
- Admin API

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.

Set the field when you create the server or patch it later. A patch replaces the stored list; send an empty array to clear it:

```
curl -sS -X PATCH "$AISIX_CP/mcp_servers/$MCP_SERVER_ID" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "forward_client_headers": ["authorization", "x-trace-*"]

  }'
```

Set the field on the existing server entry, then validate and reload the complete resources file:

resources.yaml (forward the caller's credential to an internal server)

```
mcp_servers:

  - id: d30aa2ab-77fb-4204-9fce-f1fc50f8ce77

    name: runbooks

    type: mcp

    url: https://runbooks.internal/mcp

    auth_type: none

    forward_client_headers:

      - authorization

      - x-trace-*
```

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 case                                          | Behavior                                                                                                                                                                                                                     |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Gateway credential slot                              | An 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 server | `oauth_delegate`, `oauth2_token_exchange`, and `oauth2_authorization_code` own `authorization`, so adding it to `forward_client_headers` has no effect.                                                                      |
| Protected credential or trace header                 | Credential slots, `traceparent`, `tracestate`, and AWS SigV4 headers require an exact name. Globs such as `*` or `x-*` do not match them.                                                                                    |
| Custom `api_key_header`                              | Exact-name protection does not cover a custom header automatically. A matching glob can let the caller replace the configured upstream credential.                                                                           |
| MCP session header                                   | `mcp-session-id`, `mcp-protocol-version`, and `last-event-id` are never forwarded because AISIX opens a separate upstream session.                                                                                           |

[Caller Headers AISIX Never Forwards](https://docs.api7.ai/ai-gateway/models/upstream-request-headers.md#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[​](#delegate-the-callers-token "Direct link to 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[​](#configure-a-delegate-server "Direct link to Configure a Delegate Server")

* AISIX Enterprise or Cloud
* AISIX OSS

- Dashboard
- Admin API

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.

Create the server with `auth_type: oauth_delegate` and no credential fields:

```
curl -sS -X POST "$AISIX_CP/mcp_servers" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "runbooks",

    "url": "https://runbooks.example.com/mcp",

    "auth_type": "oauth_delegate",

    "allowed_environments": ["'"$ENV_ID"'"]

  }'
```

Leave `secret`, `client_id`, `token_url`, and `scopes` unset. Switching an existing server to `oauth_delegate` clears its stored secret.

Set the mode on the existing server entry, then validate and reload the complete resources file:

resources.yaml (delegate the caller's token)

```
mcp_servers:

  - id: d30aa2ab-77fb-4204-9fce-f1fc50f8ce77

    name: runbooks

    type: mcp

    url: https://runbooks.example.com/mcp

    auth_type: oauth_delegate
```

### Which Servers Receive the Token[​](#which-servers-receive-the-token "Direct link to 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](https://docs.api7.ai/ai-gateway/mcp-gateway/tool-access-control.md) 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[​](#connect-a-client "Direct link to 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](https://code.claude.com/docs/en/mcp) 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`](https://docs.api7.ai/ai-gateway/reference/proxy-api.md#send-the-gateway-key-in-x-aisix-api-key) for how AISIX reads it.

## Optional: Verify with a Local Test Proxy[​](#optional-verify-with-a-local-test-proxy "Direct link to 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[​](#configure-aisix-to-use-the-proxy "Direct link to 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.

* AISIX Enterprise or Cloud
* AISIX OSS

- Dashboard
- Admin API

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**.

Update the server created by the setup guide:

```
curl -fsS -X PATCH "$AISIX_CP/mcp_servers/$MCP_SERVER_ID" \

  -H "Authorization: Bearer $AISIX_TOKEN" \

  -H "Content-Type: application/json" \

  --data-binary @- <<EOF | jq

{

  "url": "http://aisix-mcp-auth:3002/mcp",

  "auth_type": "bearer",

  "secret": "${MCP_UPSTREAM_TOKEN}"

}

EOF
```

Replace the existing `everything` entry and preserve the other resources:

resources.yaml (authenticated Everything server)

```
mcp_servers:

  - id: a3db3dd9-e6b0-42f9-a921-fd33f048175f

    name: everything

    type: mcp

    url: http://aisix-mcp-auth:3002/mcp

    auth_type: bearer

    secret: ${MCP_UPSTREAM_TOKEN}
```

Add `MCP_UPSTREAM_TOKEN` to the gateway container environment. Because the setup guide did not start the container with this variable, validate the complete file with the variable and recreate the container. Keep the mounts, ports, and other environment variables from the quickstart. See [Reload a Resources File](https://docs.api7.ai/ai-gateway/deployment/configuration-propagation.md#reload-a-resources-file).

For the open-source path, recreating the gateway container disconnects it from the temporary MCP network. Connect the replacement container before sending a test request:

```
docker network connect aisix-mcp "$AISIX_GATEWAY_CONTAINER"
```

### Verify a Valid Credential[​](#verify-a-valid-credential "Direct link to 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[​](#verify-a-rejected-credential "Direct link to 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[​](#next-steps "Direct link to 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](https://docs.api7.ai/ai-gateway/mcp-gateway/tool-access-control.md): scope caller API keys to specific tools, whole servers, or every tool.
* [Rate limits and budgets](https://docs.api7.ai/ai-gateway/mcp-gateway/traffic-controls.md): apply request and concurrency limits, and configure budgets for MCP tool calls.
* [Guardrails](https://docs.api7.ai/ai-gateway/mcp-gateway/guardrails.md): inspect MCP tool arguments and results.
* [Upstream request headers](https://docs.api7.ai/ai-gateway/models/upstream-request-headers.md): the same `forward_client_headers` field on the other faces AISIX proxies through, and the full list of headers no pattern can reach.
