MCP / UCP integration quickstart

Authorize an agent to search your merchant catalog through an MCP service. Your service validates the AIGW access token, retrieves a merchant access token, and calls the merchant API.

Before you start

You need:

• An AIGW Account and permission to configure a Project.
• A merchant authorization server that supports the JWT bearer grant or token exchange, with a client registered for AIGW.
• A merchant test user linked to the identity AIGW will assert. For Keycloak, link the test user.
• An HTTPS MCP endpoint and an agent with an HTTPS callback.

Use the values below consistently across the Resource, agent, and MCP service. Replace the example hosts with your own.

Value	Example	Used by
MCP endpoint / Resource indicator	https://mcp.example.com/mcp	Protected Resource Metadata, OAuth resource, AIGW access token audience, credential redemption
Merchant API	https://api.example.com/search	MCP service's downstream request
Merchant issuer	https://id.example.com/realms/merchant	AIGW Resource's Issuer URL; merchant-facing assertion aud
Merchant token endpoint	https://id.example.com/realms/merchant/protocol/openid-connect/token	AIGW's merchant-token request
Merchant client ID	aigw-search	AIGW Resource and merchant client registration
Merchant scope	search:read	Resource configuration and merchant permissions
Agent authorization scopes	openid ext_token:read search:read	User authorization; ext_token:read enables credential redemption
Agent callback	https://agent.example.com/callback	Agent registration and code exchange

The Resource indicator identifies the protected MCP service. The merchant API URL and the merchant access token's audience are separate values controlled by the merchant authorization server.

1. Configure AIGW

Owner: MCP/UCP operator.

Choose one setup path:

• DevCLI (aigw command-line tool) or coding assistant: install and log in, then create the Resource, signing key, and Proxy client. Use Codex or Claude Code from your application repository.
• Console: create the Account, Project, and Resource. Choose Token exchange, enter the values above, select private_key_jwt, and expose search:read.

New agents are approved automatically

Without a configured Agent policy, every agent is approved when it first requests a Resource. To require review, set Unverified agents and the proof rules to Hold before accepting agent requests. Review domain rules and any Resource-specific overrides as well. Agent approval does not replace user authorization or scope checks.

Before continuing:

1. Open Resource → Signing keys. Create a key if none exists, then verify that the active kid appears in the Resource JWKS.
2. Create a Proxy client in the same Project. Save its ID and one-time secret in your backend's secret store.
3. Set the Project's Agent policy. With no rules configured, new agents are approved automatically.

Save: Project ID, Resource ID, Resource authorization-server URL, Resource JWKS URL, and Proxy client credentials.

2. Configure merchant trust

Owner: merchant IAM administrator.

Use the Keycloak setup or the authorization-server requirements to:

1. Trust https://api.aigw.loginid.ai/<RESOURCE_ID> as the user-assertion issuer and its /.well-known/jwks.json as the assertion key set.
2. Configure the aigw-search client for the selected grant and client-authentication method.
3. Accept https://id.example.com/realms/merchant as the assertion audience.
4. Grant search:read and link the test user to the asserted external identity.

Ready to continue: the merchant authorization server can verify the Resource key and resolve the test user. The Active Resource badge reports saved configuration; verify token issuance during authorization below.

3. Protect your MCP endpoint

Publish this document at https://mcp.example.com/.well-known/oauth-protected-resource:

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

For an unauthenticated catalog request, return:

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"

Check the metadata and challenge before implementing the authorized call. See Protect your endpoint for error handling.

4. Authorize the agent

Owner: agent developer.

1. Discover authentication from the challenge. Save the Resource authorization endpoint, core issuer, token endpoint, and core JWKS URI.
2. Register the agent with https://agent.example.com/callback.
3. Request authorization with PKCE S256, state, nonce, resource=https://mcp.example.com/mcp, and scope=openid ext_token:read search:read.
4. Sign in as the linked test user and approve access.
5. Validate the callback and exchange the code, using the original redirect URI, PKCE verifier, and Resource indicator.

Expected result: an AIGW access token with audience https://mcp.example.com/mcp and the granted search:read and ext_token:read scopes. If the agent is Pending, the Project operator must approve it before authorization can complete.

5. Validate and redeem

The agent retries /mcp with Authorization: Bearer <AIGW_ACCESS_TOKEN>.

In your MCP handler:

1. Validate the AIGW access token against discovery's core issuer/JWKS, the MCP Resource indicator, expiry, and both required scopes.
2. Obtain a Proxy token with your Project's Proxy client using client_credentials.
3. Redeem the merchant access token with the user's AIGW access token, the Proxy token, and the exact Resource indicator:

POST https://api.aigw.loginid.ai/api/credentials/token
Authorization: Bearer <AIGW_ACCESS_TOKEN>
X-Proxy-Token: <PROXY_TOKEN>
Content-Type: application/json

{"resource":"https://mcp.example.com/mcp"}

Use the copyable retrieval commands to verify these calls from your backend terminal. Expect hasAccessToken: true.

6. Call the merchant API

Your MCP service sends the returned merchant access token to the merchant API:

GET /search?q=shoe HTTP/1.1
Host: api.example.com
Authorization: Bearer <MERCHANT_ACCESS_TOKEN>

Return the search result to the agent. Keep the merchant access token and Proxy credentials server-side.

Success: the merchant API accepts the token and returns a catalog result. A successful AIGW login alone does not prove this downstream call works.

Failing step	Check
Authorization	Agent status, HTTPS callback, PKCE, enabled identity provider, requested scopes
Token validation	Core issuer/JWKS, Resource indicator in aud, expiry, scp or scope
Proxy authentication	Proxy client ID/secret and Project
Credential redemption	ext_token:read, same Project/login, exact indicator, merchant user link and signing key
Merchant API	Merchant audience, search:read, and API permissions
410 reauthentication_required	Start a new user authorization

Use Troubleshooting for recovery steps. To inspect the request sequence with a simulated MCP service and merchant API, use the Playground.

For UCP, implement the applicable UCP operations and account linking alongside AIGW authorization and merchant-token retrieval.