Call the merchant backend
Once your MCP/UCP service has the merchant access token, use it as the merchant API expects. The merchant backend validates the token using its existing authorization-server configuration.
Example
GET /search?q=shoe HTTP/1.1
Host: api.example.com
Authorization: Bearer <MERCHANT_ACCESS_TOKEN>
The exact path, method, and scopes are merchant-specific.
Keep the trust boundaries clear
At this point there are three separate credentials with different audiences:
| Credential | Held by | Used for |
|---|---|---|
| AIGW access token | Agent, then MCP/UCP service | Proves the user/agent authorization to AIGW/MCP flow |
| Proxy token | MCP/UCP service | Proves the server/project identity to AIGW |
| Merchant access token | MCP/UCP service | Authorizes the downstream merchant API call |
The agent must never receive the proxy token or the merchant access token. The merchant backend should normally see only the merchant access token it already trusts.
Scope handling
Requested AIGW resource scopes are intersected with the scopes exposed by the resource before AIGW sends them to the merchant authorization server. The merchant AS must define the same scope names and decide how those scopes map to API permissions.
For example, an MCP tool search_products might map to search:read, while a checkout tool could require a different merchant scope. Keep the mapping explicit in your MCP/UCP implementation so a tool cannot silently use a broader token than necessary.
Token lifetime and caching
AIGW caches the merchant access token and refreshes it when possible; otherwise the user must authorize again. Your MCP/UCP service should also avoid repeatedly asking for a new proxy token on every request. Keep local caching bounded by the token expiration and your security policy.
Failure handling
Distinguish downstream failures from AIGW authorization failures. Examples:
- credential redemption fails → do not call the merchant API;
- merchant access token lacks a required scope → return an authorization error rather than retrying blindly;
- merchant API returns
401because the token expired/revoked → obtain/redeem again according to your token policy; - merchant API returns a business error → pass a suitable MCP/UCP-level error back to the agent without exposing internal credentials.
After you can complete one successful downstream call, your basic MCP/UCP integration is complete. Use Troubleshooting for common setup failures.