PingOne

MCP servers

A Model Context Protocol (MCP) server is the fundamental unit of access control in PingOne Authorize that represents the MCP server you want to protect.

An MCP server in PingOne Authorize describes the RPC endpoints that you want to control access to. You can register multiple RPC endpoint URLs on a single MCP server, so one configuration can protect the same MCP server hosted on multiple origins. After you define an MCP server and connect an MCP gateway, PingOne Authorize can instruct the gateway to block access for unauthorized MCP clients and allow it only for authorized clients.

MCP servers are managed separately from API services, which represent conventional APIs.

Protected Resource Metadata document

The MCP specification requires MCP servers to implement OAuth 2.1 Protected Resource Metadata (RFC 9728). A PRM document lets an MCP server, acting as an OAuth 2.1 resource server, advertise which authorization servers can issue access tokens for it.

MCP clients can discover the PRM document from the resource_metadata URL in the WWW-Authenticate header of a challenge response. When PingOne Authorize returns a challenge response for an MCP server, the challenge includes the PRM URL that you configured for the MCP server.

The PRM URL interacts with the RPC endpoint URLs that you configure on the MCP server. You can use an absolute URL or a relative URL for the PRM document:

  • An absolute URL is returned unchanged in every challenge response for the MCP server. Because the URL is the same for every request, you can use an absolute URL only if the MCP server has a single RPC endpoint URL. The URL must use the https scheme and can’t include a fragment.

  • A relative URL is combined with the RPC endpoint URL that matched the client’s request. PingOne Authorize constructs the complete PRM URL from the origin of the matched RPC endpoint URL, the relative URL, and the endpoint’s path. If the MCP server has multiple RPC endpoint URLs, use a relative URL so that each origin can serve its own PRM document.

The following examples show the PRM URL in the challenge response when the relative URL is /.well-known/oauth-protected-resource, the recommended value:

RPC endpoint URL that matched the request PRM URL in the challenge response

https://mcp.example.com

https://mcp.example.com/.well-known/oauth-protected-resource

https://example.com/mcp

https://example.com/.well-known/oauth-protected-resource/mcp

Although PingOne Authorize populates the challenge header with the configured PRM URL, you’re responsible for ensuring that the URL resolves to a valid PRM document. PingOne Authorize doesn’t generate this document.

Learn how to configure the PRM URL in Defining your MCP server in PingOne Authorize.

Token management

When you define an MCP server, you can use PingOne SSO to issue access tokens and manage users for the MCP server, or you can use external token sources such as PingOne Advanced Services or PingOne Advanced Identity Cloud.

PingOne SSO token source

If you use PingOne SSO to issue tokens for the MCP server, PingOne Authorize works with PingOne resources and applications to manage access control for your MCP server. You can also define custom policies that handle more complex authorization scenarios.

Each MCP server is associated with a PingOne resource. This resource is a representation of your MCP server for OAuth authorization purposes. Resources have scopes that are used in access token configuration. Scopes determine which resources a client can access. PingOne Authorize uses scopes to:

  • Ensure that the access token presented by an MCP client was issued for your MCP server. In this basic access control check, PingOne Authorize:

    • Uses the access token’s scopes to determine which PingOne resource is being requested.

    • Verifies that the access token’s audience matches the audience for the PingOne resource.

    After you define an MCP server, make sure that you add a PingOne application that’s allowed to access the protected MCP server.

  • Determine the extent of access allowed to a client. For example, your MCP server might require a tools:read scope for reading tool listings and a tools:write scope for invoking tools that modify data. You can enforce these requirements with the auth-challenge statement in custom policies.

When authorizing an HTTP request, if the request’s access token includes a subject, PingOne Authorize automatically populates the built-in PingOne.User attribute with the requesting user’s data.

External token source

If access tokens come from an external token source, PingOne Authorize validates the access token. If the token is valid, PingOne Authorize provides its claims to custom policies, which can use them for claims-based access control. Built-in access control rules aren’t available for externally sourced tokens.

PingOne Authorize doesn’t automatically provide identity information about the requesting user in built-in user attributes when tokens come from an external source. Instead, if the request’s access token includes a subject claim, you can use the PingOne.API Access Management.Identity.Access Token.Subject attribute to resolve user identity information from an external directory. Learn more in API Access Management attributes.

Learn more about external token sources in External OAuth servers in PingOne Authorize.

Modules

When you enable custom policies for an MCP server, PingOne Authorize automatically creates a system-owned module for that server. Each module has its own policy tree and version history independent of other modules, and shares a Trust Framework through the Default module.

Policy deployment

Each MCP server has a system-owned decision endpoint for managing and deploying its authorization policies. Learn more in Deploying an MCP server.