Protect your MCP / UCP endpoint

Your MCPMCPModel Context Protocol: a standard way for AI agents to call tools and data sources exposed by a server./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 metadata document from your MCP/UCP origin. The exact path may follow RFC 9728 conventions; the tested flow uses /.well-known/oauth-protected-resource.

Example:

GET /.well-known/oauth-protected-resource HTTP/1.1
Host: mcp.example.com

{
  "resource": "https://mcp.example.com",
  "authorization_servers": [
    "https://api.aigw.eval.loginid.ai/<RESOURCE_ID>"
  ]
}

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

AIGW's ResourceResourceThe downstream system registered in a Project. Its kind (Token exchange or OAuth client) decides the role AIGW plays. Reference page (and the Resource's Configuration tab) has a Download oauth-protected-resource.json button intended for this purpose. Adjust resource to your MCP/UCP service URL before publishing it.

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 realm="mcp", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource", scope="mcp:tools"

The supplied playground starts with exactly 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:

• the merchant authorization-server client secret or private key;
• the MCP/UCP server's proxy-client secret;
• the proxy tokenProxy tokenA short-lived token the MCP/UCP service gets with its Proxy client, sent as X-Proxy-Token when redeeming a merchant token.;
• the merchant access tokenMerchant access tokenA token issued by the merchant's own authorization server. Only the MCP/UCP service sees it, never the agent..

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 + PKCEPKCEProof Key for Code Exchange: binds an authorization request to the later code exchange so a stolen code is useless.;
7. obtain an AIGW access tokenAIGW access tokenThe token an agent receives after the user authorizes it. It says which user approved which agent for which scopes.;
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 redemptionCredential redemptionPOST /api/credentials/token: the MCP/UCP service trades the user's AIGW token plus its Proxy token for the merchant access token..
• Valid AIGW token but insufficient authorization → return an appropriate authorization error and include enough metadata/scope information for the agent to request the required permission.

The supplied notes verify the discovery and authorization flow but do not define a complete error taxonomy for every MCP/UCP failure mode. Keep your implementation aligned with your MCP/UCP framework and OAuth protected-resource behavior.