Skip to main content
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

Add oauth_client_metadata in Advanced Configuration when setting up your MCP integration in the MCP Registry. 
{
  "oauth_client_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": ["[email protected]"],
    "tos_uri": "https://yourcompany.com/terms",
    "policy_uri": "https://yourcompany.com/privacy"
  }
}

​
Available Fields

FieldTypeDescription
client_namestringName shown during OAuth consent
client_uristringOrganization’s homepage URL
logo_uristringLogo shown during consent (should be HTTPS)
scopestringSpace-separated OAuth scopes to request
software_idstringUnique client identifier (useful for pre-registered clients)
software_versionstringClient software version
grant_typesstring[]OAuth grant types (default: ["authorization_code", "refresh_token"])
response_typesstring[]OAuth response types (default: ["code"])
token_endpoint_auth_methodstringToken endpoint auth method (default: "none")
contactsstring[]Contact email addresses
tos_uristringTerms of Service URL
policy_uristringPrivacy policy URL

​
Default Values

If not customized, Portkey uses:
FieldDefault Value
client_name"Portkey (workspaceId/serverId)"
client_uri"https://portkey.ai"
logo_uriPortkey 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.

​
Example: Enterprise Compliance

Your enterprise requires all OAuth registrations to include legal contact information and link to corporate policies: 
{
  "oauth_client_metadata": {
    "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": ["[email protected]", "[email protected]"],
    "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: 
{
  "oauth_client_metadata": {
    "software_id": "registered-client-12345",
    "client_name": "Pre-Registered MCP Client"
  }
}

​
Example: Custom Scopes

Request specific OAuth scopes from the MCP server: 
{
  "oauth_client_metadata": {
    "scope": "read:projects write:issues admin:webhooks"
  }
}
The authorization server will request consent for these specific scopes.
TopicDescription
Authentication OverviewHow authentication layers work
External MCP ServersAdding OAuth-protected external servers