OAuth Client Metadata

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

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

Configuration

Add oauth_metadata in Advanced Configuration when setting up your MCP integration in the MCP Registry.

{
  "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": ["support@yourcompany.com"],
    "tos_uri": "https://yourcompany.com/terms",
    "policy_uri": "https://yourcompany.com/privacy"
  }
}

Available Fields

Field	Type	Description
`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

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.

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": ["security@acme.com", "legal@acme.com"],
    "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_metadata": {
    "software_id": "registered-client-12345",
    "client_name": "Pre-Registered MCP Client"
  }
}

Example: Custom Scopes

Request specific OAuth scopes from the MCP server:

{
  "oauth_metadata": {
    "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
`redirect_uri`	Must be `https://mcp.portkey.ai/oauth/upstream-callback`
`scope`	Scopes to request during authorization

GitHub example:

{
  "oauth_metadata": {
    "client_id": "Iv1.a1b2c3d4e5f6g7h8",
    "client_secret": "your_github_oauth_client_secret",
    "redirect_uri": "https://mcp.portkey.ai/oauth/upstream-callback",
    "scope": "repo read:org"
  }
}

The redirect_uri configured in Portkey must exactly match the Authorization callback URL set when creating the GitHub OAuth App.

See the GitHub MCP server guide for complete setup instructions.

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

Introduction

Product

Self-Hosting

Support

When to Use

How It Works

Configuration

Available Fields

Default Values

Security Notes

redirect_uris Cannot Be Customized

Fields That Cannot Be Set

Example: Enterprise Compliance

Example: Pre-Registered Client

Example: Custom Scopes

Example: Servers Without Dynamic Client Registration (GitHub)

​When to Use

​How It Works

​Configuration

​Available Fields

​Default Values

​Security Notes

​redirect_uris Cannot Be Customized

​Fields That Cannot Be Set

​Example: Enterprise Compliance

​Example: Pre-Registered Client

​Example: Custom Scopes

​Example: Servers Without Dynamic Client Registration (GitHub)

​Related

When to Use

How It Works

Configuration

Available Fields

Default Values

Security Notes

redirect_uris Cannot Be Customized

Fields That Cannot Be Set

Example: Enterprise Compliance

Example: Pre-Registered Client

Example: Custom Scopes

Example: Servers Without Dynamic Client Registration (GitHub)

Related