Skip to main content

Protect your MCP / UCP endpoint

Your MCP/UCP endpoint should behave like an OAuth protected resource. Its first job is not to redirect the agent itself; its job is to tell the agent where authorization is defined.

Publish OAuth Protected Resource Metadata​

Serve a Protected Resource Metadata document from your MCP/UCP origin. This example uses /.well-known/oauth-protected-resource. Advertise its URL in the resource_metadata parameter of your authentication challenge.

Example:

GET /.well-known/oauth-protected-resource HTTP/1.1
Host: mcp.example.com
{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": [
    "https://api.aigw.loginid.ai/<RESOURCE_ID>"
  ],
  "scopes_supported": ["search:read", "ext_token:read"]
}

authorization_servers[0] points to the per-resource AIGW authorization-server base URL, not the global core token host.

AIGW's Resource Reference page (and the Resource's Configuration tab) has a Download oauth-protected-resource.json button intended for this purpose. Keep resource equal to the indicator registered for this integration. For MCP, set the Resource indicator to your canonical MCP endpoint, such as https://mcp.example.com/mcp, and use that same value in metadata, OAuth requests, token validation, and credential redemption. The downstream merchant API can have a different URL and token audience. If the download includes jwks_uri, that is the Resource assertion keyset, not the platform-token verification keyset returned by AIGW discovery.

Resource reference

Return a 401 challenge​

When a request has no acceptable bearer token, return an OAuth challenge and include the metadata URL.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource", scope="search:read ext_token:read"

The Playground demonstrates this pattern: Agent → MCP → 401, then the agent fetches the protected-resource metadata and discovers AIGW.

Do not leak merchant configuration​

The agent needs the AIGW authorization-server location. It does not need:

Those remain server-side.

What the agent does next​

A standards-aware agent should:

  1. parse resource_metadata from WWW-Authenticate;
  2. fetch the metadata document;
  3. read authorization_servers;
  4. fetch AIGW discovery from the per-resource authorization server;
  5. register dynamically if needed;
  6. start Authorization Code + PKCE;
  7. obtain an AIGW access token;
  8. retry your MCP/UCP endpoint.

Your MCP/UCP code does not need to implement those agent-side steps. See Agent Integration if you also own the agent.

Production behavior​

For production, define how your server distinguishes these cases:

  • No token → return 401 + metadata pointer.
  • Malformed/invalid token → return 401; do not proceed to credential redemption.
  • Valid AIGW access token but insufficient authorization → return an appropriate authorization error and include enough metadata/scope information for the agent to request the required permission.

Use your MCP/UCP framework's protocol error handling for tool and application failures. Use the OAuth challenge for missing or invalid bearer credentials; do not turn every application error into a new authorization request.