> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portkey.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Advanced Configuration
> Control how the gateway authenticates, forwards context, and connects to upstream MCP servers.
When you add an MCP server to the registry, the UI handles the basics — server name, URL, auth type, static headers. That's enough for most setups.
Advanced Configuration is the JSON field at the bottom of the integration form.
It unlocks everything the UI fields don't cover:
* **Forward runtime headers** like trace IDs or tenant context to the upstream server
* **Tell the MCP server who's calling** by forwarding authenticated user identity
* **Validate tokens at the edge** before requests ever reach the upstream server
* **Customize OAuth behavior** when the upstream server's defaults don't work
* **Bring your own auth** with an external identity provider for enterprise SSO
***
## What You Can Configure
| Key | What it does | When you need it |
| ------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------ |
| [`forward_headers`](#forward-headers) | Pass client request headers to the upstream server | Distributed tracing, tenant context, custom metadata |
| [`oauth_metadata`](#oauth-metadata) | Override OAuth discovery defaults | Upstream server needs non-standard OAuth config |
| [`user_identity_forwarding`](#user-identity-forwarding) | Tell the upstream server *who* is making the request | Per-user authorization, audit logging, personalization |
| [`jwt_validation`](#jwt-validation) | Validate client JWTs at the gateway edge | Bring-your-own IdP, enforce auth before proxying |
| [`external_auth_config`](#external-auth-config) | Use an external OAuth provider instead of Portkey's | Enterprise SSO with your own IdP |
***
## Forward Headers
Forward specific headers from the incoming client request to the upstream MCP server. Unlike static headers, these are dynamic — they capture whatever the client sends at runtime.
Two modes: **allowlist** (only forward listed headers) and **all-except** (forward everything except listed headers).
```json theme={"system"}
{
"forward_headers": ["X-Request-Id", "X-Trace-Id", "X-Tenant-Id"]
}
```
Forwarded headers have the **lowest priority** — they never override auth headers or static values you've configured.
Allowlist vs all-except modes, priority rules, and full configuration options.
***
## OAuth Metadata
Override the OAuth endpoints and parameters that Portkey discovers from the upstream server's `/.well-known/oauth-authorization-server`. Only relevant when Auth Type is **OAuth 2.1**.
```json theme={"system"}
{
"oauth_metadata": {
"authorization_endpoint": "https://auth.example.com/authorize",
"token_endpoint": "https://auth.example.com/token",
"scopes_supported": ["read", "write", "admin"]
}
}
```
All fields are optional. Provided values override auto-discovered defaults.
Full list of overridable OAuth fields and registration customization.
***
## User Identity Forwarding
After authenticating a user, Portkey can forward their identity to the upstream MCP server. The server gets to know *who* is making the request — without implementing its own auth.
Three methods:
| Method | What the upstream server receives |
| --------------- | ------------------------------------------------------ |
| `claims_header` | JSON object with user claims in `X-User-Claims` header |
| `bearer` | Original OAuth access token in `Authorization` header |
| `jwt_header` | Portkey-signed JWT with claims in `X-User-JWT` header |
```json theme={"system"}
{
"user_identity_forwarding": {
"method": "claims_header",
"include_claims": ["sub", "email", "workspace_id"]
}
}
```
Method comparison, claim selection, custom headers, and JWT verification.
***
## JWT Validation
Validate incoming client JWTs **before** proxying to the upstream server. The gateway rejects invalid tokens at the edge — the upstream server never sees them.
Supports three validation methods: **JWKS URI**, **inline JWKS keys**, and **token introspection** (RFC 7662). You can also enforce required claims and match claim values.
```json theme={"system"}
{
"jwt_validation": {
"jwksUri": "https://auth.example.com/.well-known/jwks.json",
"algorithms": ["RS256"],
"requiredClaims": ["sub", "email"]
}
}
```
JWKS, introspection, claim matching (exact, contains, regex), and full options reference.
***
## External Auth Config
Enterprise only — available for self-hosted deployments.
Use an external identity provider (Okta, Auth0, Azure AD, Cognito) instead of Portkey's built-in OAuth. Users authenticate with corporate credentials.
```json theme={"system"}
{
"external_auth_config": {
"authorization_endpoint": "https://idp.example.com/authorize",
"token_endpoint": "https://idp.example.com/token",
"scope": "openid profile mcp"
}
}
```
Supports both dynamic client registration and pre-registered client credentials.
Full setup for external OAuth providers, dynamic registration, and pre-registered credentials.
***
## Combining Options
You can combine multiple keys in a single configuration:
```json theme={"system"}
{
"forward_headers": ["X-Request-Id", "X-Trace-Id"],
"user_identity_forwarding": {
"method": "claims_header",
"include_claims": ["sub", "email", "workspace_id"]
},
"jwt_validation": {
"jwksUri": "https://auth.example.com/.well-known/jwks.json",
"requiredClaims": ["sub"],
"claimValues": {
"iss": {
"values": "https://auth.example.com",
"matchType": "exact"
}
}
}
}
```
This validates the client JWT, forwards trace headers, and sends user identity to the upstream — all in one integration.