OAuth Client Metadata

Customize OAuth client metadata for MCP servers.

When Portkey connects to OAuth-protected MCP servers using OAuth Auto, it registers as an OAuth client with the server’s authorization endpoint. By default, Portkey uses standard client metadata. For compliance or branding requirements, you can customize this.

When to Use

Customize OAuth client metadata when:

• The OAuth server requires a pre-registered software_id or specific scopes
• You need custom branding during OAuth consent screens (your company name/logo instead of Portkey’s)
• Compliance requires specific contact info, terms of service, or privacy policy URLs
• The MCP server expects specific OAuth client configuration

---

How It Works

When a user first accesses an OAuth-protected MCP server, Portkey initiates the OAuth flow. As part of this process, Portkey presents client metadata to the authorization server (per RFC 7591 - OAuth 2.0 Dynamic Client Registration).

1. User requests tool from MCP server
2. Portkey initiates OAuth flow with authorization server
3. Authorization server shows consent screen with client metadata
4. User sees your company name/logo instead of default Portkey branding
5. User authorizes access
6. Flow completes normally

---

Configuration

When setting up your MCP integration in the MCP Registry, expand Advanced Settings and paste your client metadata into the OAuth Metadata field as a plain JSON object:

{
  "client_name": "Your Company Name",
  "client_uri": "https://yourcompany.com",
  "logo_uri": "https://yourcompany.com/logo.png",
  "software_id": "com.yourcompany.mcp-gateway",
  "scope": "mcp:servers:read mcp:tools:execute",
  "contacts": ["[e-mail]"],
  "tos_uri": "https://yourcompany.com/terms",
  "policy_uri": "https://yourcompany.com/privacy"
}

Do not wrap this in an outer oauth_metadata key when using the OAuth Metadata field. The field’s contents are stored as your OAuth metadata directly, so an extra wrapper nests your settings one level too deep and Portkey ignores them silently — including a client_id, which causes Portkey to fall back to Dynamic Client Registration.

The wrapper is only correct in the separate Advanced Configuration JSON box, which merges its top-level keys into the integration’s configuration:

{
  "oauth_metadata": {
    "client_name": "Your Company Name",
    "client_uri": "https://yourcompany.com",
    "logo_uri": "https://yourcompany.com/logo.png",
    "software_id": "com.yourcompany.mcp-gateway",
    "scope": "mcp:servers:read mcp:tools:execute",
    "contacts": ["[e-mail]"],
    "tos_uri": "https://yourcompany.com/terms",
    "policy_uri": "https://yourcompany.com/privacy"
  }
}

All the examples on this page show the contents of the OAuth Metadata field. If you use the Advanced Configuration box instead, nest each one under oauth_metadata.

---

Available Fields

Field	Type	Description
client_id	string	Pre-registered OAuth client ID. Setting this disables Dynamic Client Registration for the integration
client_secret	string	Pre-registered OAuth client secret, for confidential clients
client_name	string	Name shown during OAuth consent
client_uri	string	Organization’s homepage URL
logo_uri	string	Logo shown during consent (should be HTTPS)
scope	string	Space-separated OAuth scopes to request
software_id	string	Unique client identifier (useful for pre-registered clients)
software_version	string	Client software version
grant_types	string[]	OAuth grant types (default: ["authorization_code", "refresh_token"])
response_types	string[]	OAuth response types (default: ["code"])
token_endpoint_auth_method	string	Token endpoint auth method (default: "none")
contacts	string[]	Contact email addresses
tos_uri	string	Terms of Service URL
policy_uri	string	Privacy policy URL
authorization_params	object	Extra query parameters appended to the upstream authorization URL (string values only)

---

Default Values

If not customized, Portkey uses:

Field	Default Value
client_name	"Portkey (workspaceId/serverId)"
client_uri	"https://portkey.ai"
logo_uri	Portkey logo
software_id	"ai.portkey.mcp"
grant_types	["authorization_code", "refresh_token"]
response_types	["code"]
token_endpoint_auth_method	"none"

---

Security Notes

redirect_uris Cannot Be Customized

The redirect_uris field is never customizable. Portkey always uses its own callback URL for OAuth flows:

<gateway-url>/oauth/upstream-callback

This ensures OAuth tokens are delivered securely to Portkey’s gateway, not to an arbitrary URL.

Fields That Cannot Be Set

The following fields are excluded from customization:

• redirect_uris - Must be gateway-controlled for security
• jwks_uri - Not yet supported
• jwks - Not yet supported
• software_statement - Not yet supported

If you include these fields, they’re ignored.

Authorization Parameters That Cannot Be Set

authorization_params cannot override the parameters Portkey and the MCP SDK own, because doing so would break PKCE or the callback correlation:

response_type, client_id, client_secret, code_challenge, code_challenge_method, redirect_uri, state, scope, resource

Any of these keys in authorization_params are ignored and logged as a warning. Use the scope field of oauth_metadata to change requested scopes.

---

Example: Enterprise Compliance

Your enterprise requires all OAuth registrations to include legal contact information and link to corporate policies:

{
  "client_name": "Acme Corp MCP Gateway",
  "client_uri": "https://acme.com",
  "logo_uri": "https://acme.com/assets/logo.png",
  "software_id": "com.acme.mcp-gateway",
  "software_version": "1.0.0",
  "scope": "mcp:read mcp:write",
  "contacts": ["[e-mail]", "[e-mail]"],
  "tos_uri": "https://acme.com/legal/terms",
  "policy_uri": "https://acme.com/legal/privacy"
}

When users authorize access, they see “Acme Corp MCP Gateway” with your logo instead of generic Portkey branding.

---

Example: Pre-Registered Client

Some OAuth servers require clients to be pre-registered with a specific software_id:

{
  "software_id": "registered-client-12345",
  "client_name": "Pre-Registered MCP Client"
}

---

Example: Custom Scopes

Request specific OAuth scopes from the MCP server:

{
  "scope": "read:projects write:issues admin:webhooks"
}

The authorization server will request consent for these specific scopes.

---

Example: Servers Without Dynamic Client Registration (GitHub)

Some MCP servers like GitHub don’t support OAuth Dynamic Client Registration (DCR). For these servers, create an OAuth App manually and provide the credentials to Portkey.

Required fields for non-DCR servers:

Field	Description
client_id	OAuth App client ID from the service
client_secret	OAuth App client secret from the service (only for confidential apps)
scope	Scopes to request during authorization
token_endpoint_auth_method	Set to client_secret_post or client_secret_basic if the OAuth App is registered as a confidential/web client. The default is none, which such apps reject at token exchange.

Providing a client_id disables Dynamic Client Registration entirely for that integration — Portkey presents the client you configured instead of trying to register a new one.

GitHub example:

{
  "client_id": "Iv1.a1b2c3d4e5f6g7h8",
  "client_secret": "your_github_oauth_client_secret",
  "scope": "repo read:org"
}

Set the OAuth App’s Authorization callback URL to Portkey’s callback, <gateway-url>/oauth/upstream-callback. On Portkey’s managed gateway that is https://mcp.portkey.ai/oauth/upstream-callback; on a self-hosted or hybrid deployment, use your own gateway host (the value of MCP_GATEWAY_BASE_URL). This URL is always controlled by the gateway, so a redirect_uri set in your OAuth metadata is ignored.

See the GitHub MCP server guide for complete setup instructions.

---

Example: Provider-Specific Authorization Parameters (Google)

Some providers require query parameters on the authorization request that the OAuth spec doesn’t define. Google is the common case: it only returns a refresh token when the authorization request carries access_type=offline, and only re-issues one for a user who has already consented when prompt=consent is also present.

Without a refresh token, Portkey has nothing to renew the connection with, so the user is pushed back through consent once the access token expires (one hour for Google).

Add these with authorization_params:

{
  "oauth_metadata": {
    "client_id": "...apps.googleusercontent.com",
    "client_secret": "your_google_oauth_client_secret",
    "redirect_uri": "https://mcp.portkey.ai/oauth/upstream-callback",
    "scope": "https://www.googleapis.com/auth/drive.readonly",
    "authorization_params": {
      "access_type": "offline",
      "prompt": "consent"
    }
  }
}

Portkey appends every key in authorization_params to the upstream authorization URL on each auth flow. Values must be strings; non-string values are ignored.

Connections authorized before this setting was added have no stored refresh token, and Google skips consent for a user who has already granted access — so the setting alone won’t fix them. Remove the affected user’s connection and have them authorize again; prompt=consent guarantees a refresh token on that pass.

For external authorization providers, set authorization_params inside external_auth_config instead.

Troubleshooting

Portkey still attempts Dynamic Client Registration even though I set a client_id. Portkey resolved no client ID from your configuration, so it fell back to registration. Check that the JSON in the OAuth Metadata field has client_id at the top level, with no outer oauth_metadata wrapper. If you configured it through the Advanced Configuration box instead, the wrapper is required there — but it must appear exactly once.

Consent succeeds, then the token exchange fails. The client ID is being presented correctly and the failure is now on the provider side. In order of likelihood: the OAuth App is registered as a confidential/web client while Portkey defaults to token_endpoint_auth_method: "none" (set it explicitly, and supply client_secret); the callback URL registered on the provider doesn’t exactly match <gateway-url>/oauth/upstream-callback; or the app is missing a granted scope or the refresh_token grant, which Portkey requests by default.

---

Related

Topic	Description
Authentication Overview	How authentication layers work
External MCP Servers	Adding OAuth-protected external servers

---

Portkey is now PRISMA AIRS AI Gateway. See it in action.

Contact Us