Skip to main content

Call MCP / UCP

Retry the original MCP/UCP operation with the AIGW access token:

POST /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer <AIGW_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-06-18

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

This MCP example lists tools after session initialization. Send the protocol version negotiated during initialization and, if the server issued one, include Mcp-Session-Id: <MCP_SESSION_ID>. For UCP, retry the original operation with its required payload.

The MCP/UCP service uses that AIGW access token together with its own server credential to obtain the merchant access token. The agent does not participate in the merchant token exchange.

What success means for the agent​

From the agent's perspective, the authorization flow is complete when:

  • the MCP/UCP service accepts the AIGW access token;
  • the requested tool/operation executes or returns a normal business response;
  • future calls can reuse the token while it remains valid and sufficiently scoped.

Handling insufficient authorization​

When an MCP operation needs a scope the token does not grant, the service returns 403 Forbidden with an insufficient_scope challenge. For an operation requiring search:read:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="search:read", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"

Run authorization again with the required scopes, exchange the new code, and retry using the new AIGW access token. A missing, expired, or invalid token instead receives 401 Unauthorized. See the MCP authorization specification and Streamable HTTP transport.

Keep merchant credentials opaque​

Use the AIGW access token to call the MCP/UCP service. AIGW and the service handle the merchant access token server-side; never send it to the agent.