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 is never forwarded or exposed to the upstream MCP server.

Set the credential with the auth_type field and any fields required by that authentication mode when you register or update an MCP server.

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

The secret holds the plaintext credential AISIX presents upstream. 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.

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 "http://127.0.0.1:3001/admin/v1/mcp_servers" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "runbooks",
    "url": "https://runbooks.internal/mcp",
    "auth_type": "none"
  }'

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

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 "http://127.0.0.1:3001/admin/v1/mcp_servers" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "github",
    "url": "https://mcp.example.com/mcp",
    "auth_type": "bearer",
    "secret": "YOUR_UPSTREAM_MCP_TOKEN"
  }'

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

❷ secret is required and must be non-empty.

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 "http://127.0.0.1:3001/admin/v1/mcp_servers" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "catalog",
    "url": "https://catalog.example.com/mcp",
    "auth_type": "api_key",
    "secret": "YOUR_UPSTREAM_API_KEY"
  }'

❶ 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

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 "http://127.0.0.1:3001/admin/v1/mcp_servers" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_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"]
  }'

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

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. Other registered MCP servers keep working. AISIX logs the failure and does not expose credential details to the calling agent.

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 limits, concurrency limits, and budgets to MCP tool calls.
Guardrails: inspect MCP tool arguments and results.

Authentication Modes​

No Authentication​

Bearer Token​

API Key​

OAuth 2.0 Client Credentials​

Credential Handling​

Next Steps​