Configure AIGW for an MCP / UCP integration
Use the AIGW Console to register the merchant Resource, configure agent access, and create credentials for your MCP/UCP service.
Before you start
Collect the merchant-side information below before creating the Token exchange Resource. If you are a third-party MCP provider, request these values from the merchant API/IAM owner.
| You need | Ask whom | Where they normally find it |
|---|---|---|
| MCP Resource indicator | MCP operator, agreed with merchant IAM | Canonical HTTPS endpoint of the protected MCP service |
| Merchant Authorization Server issuer | Merchant IAM owner | OAuth/OIDC discovery metadata |
| Merchant token endpoint | Merchant IAM owner | OAuth/OIDC discovery metadata |
| Client ID for AIGW | Merchant IAM owner | Client/application registered for AIGW |
| Supported authentication/grant method | Merchant IAM owner | Authorization Server/client configuration |
| Merchant scopes | Merchant API/IAM owner | API scopes/permissions configuration |
| User mapping expectation | Merchant IAM owner | How merchant accounts are identified, e.g. email/subject mapping |
Agree the merchant Client ID and endpoints, then create the Resource. Verify its active signing key before giving its per-resource issuer and JWKS URL to the merchant IAM administrator. See Create and verify a signing key for Console and DevCLI (aigw command-line tool) steps.
1. Account
An Account is the top-level AIGW tenant. It contains Projects and account-level administration.
| Field | What it is | How to choose it | Where it is used |
|---|---|---|---|
| Account name | Friendly tenant/organization name | Use the MCP provider or merchant organization name | Console identification and account administration |
Ownership: if a third-party MCP provider operates the integration, the provider normally owns this AIGW Account. If the merchant operates its own MCP/UCP, the merchant normally owns it.
2. Project
A Project isolates the integration's Resources, Agents, End Users, and Proxy clients.
Go to Project Management → New Project. The only input is the Project name; you can rename it later.
| Field | What it is | How to choose it | Where it is used |
|---|---|---|---|
| Project name | Human-readable integration/environment name | Prefer merchant + integration + environment, e.g. Acme MCP dev | Console organization |
The user AIGW access token and Proxy token used in credential redemption must belong to the same Project. Do not create the MCP/UCP server credential in an unrelated Project.
3. Register a Resource
A Resource describes the protected/downstream system and determines which AIGW integration model is used.
Open Project → Resources → Register resource. For a Token exchange Resource the wizard has four steps: Identity & endpoint → Authentication → Exchange & scopes → Reference.
3.1 Choose Resource kind
| Option | What it means | Use it when | What AIGW does |
|---|---|---|---|
| Token exchange | The protected merchant system has its own Authorization Server and AIGW needs a merchant credential | Typical agent + MCP/UCP delegated-access scenario | Authenticates/authorizes the user and obtains/caches a merchant access token for downstream use |
| OAuth client | An application uses AIGW directly for human sign-in | Traditional web/app authentication where AIGW is the IdP/authorization service | Creates OAuth client configuration so the application can redirect users to AIGW and receive AIGW-issued identity/tokens |
Choose Token exchange for delegated access to the merchant API. See Resources for both Resource kinds.
3.2 Identity & endpoint (wizard step 1)
| Field | What it is | Where to get it | How AIGW uses it | Example |
|---|---|---|---|---|
| Display name | Friendly name for this Resource | Choose it yourself | Console/user-facing identification | Acme Search API |
| Resource indicator | Canonical protected MCP endpoint | MCP operator, agreed with merchant IAM | Binds the AIGW access token to the MCP service and selects the Resource during credential redemption | https://mcp.example.com/mcp |
| Issuer URL | Issuer identifier of the merchant Authorization Server (often a different host than the Resource indicator) | Merchant OAuth/OIDC metadata or IAM admin | Establishes which merchant AS AIGW communicates with / targets | https://id.example.com/realms/merchant |
| Token endpoint | OAuth token endpoint of the merchant AS | Merchant OAuth/OIDC metadata or IAM admin | Endpoint AIGW calls for the configured grant/exchange | https://id.example.com/realms/merchant/protocol/openid-connect/token |
Resource indicator rule: treat this as an exact protocol identifier. Later, the MCP/UCP backend sends the same value in POST /api/credentials/token. A display-name variation or different URL is not interchangeable.
3.3 Authentication (wizard step 2): choose how AIGW obtains the merchant access token
Step 2 asks for the Client ID (see 3.4) and a Client authentication method. The dropdown values are private_key_jwt (default), client_secret_basic, and token_exchange. This AIGW field selects a merchant-token request pattern: the label includes both grant selection and client authentication. Match the complete pattern below with the merchant IAM administrator.
| Choice | What it does | Merchant-side requirement | Availability |
|---|---|---|---|
Private Key JWT (private_key_jwt) | AIGW uses an RFC 7523 JWT bearer user assertion plus private_key_jwt client authentication | Merchant AS must trust the per-resource AIGW issuer/JWKS and have the AIGW client configured for JWT client authentication | Supported; use this for the Keycloak configuration |
Token Exchange (token_exchange) | AIGW uses RFC 8693 with an external AIGW-signed subject token | Merchant AS must support/configure the corresponding token-exchange flow and trust the AIGW assertion | Supported; configure the merchant-specific exchange parameters |
Client Secret Basic (client_secret_basic) | Authenticates AIGW with a client ID/secret over HTTP Basic | Merchant AS client needs secret-based client authentication | Coming soon. Use private_key_jwt or token_exchange to obtain merchant tokens |
For this integration, use private_key_jwt or token_exchange as agreed with the merchant IAM administrator. Standalone client_secret_basic support for merchant-token provisioning is Coming soon. A secret configured within the token_exchange pattern is a separate choice.
Token exchange request settings
When Client authentication is token_exchange, enter a Client secret only if the merchant authorization server requires HTTP Basic client authentication. Without a secret, AIGW uses a signed client assertion.
Expand Exchange request to match the merchant authorization server's requirements:
| Setting | Default | How to configure it |
|---|---|---|
| Send resource indicator | On | Sends the Resource indicator as resource. Turn it off if the merchant server rejects this parameter |
| Send requested token type | On | Sends requested_token_type=urn:ietf:params:oauth:token-type:access_token. Turn it off if the merchant server rejects this parameter |
| Audience | Empty | Sends the merchant-specific audience parameter when provided. This does not change the aud claim in the signed subject token |
| Subject token type | urn:ietf:params:oauth:token-type:jwt | Leave empty to use the default, or enter the identifier required by the merchant server |
If Send resource indicator is off and Audience is empty, the merchant authorization server chooses the audience of the token it issues.
3.4 Client ID
The Client ID identifies AIGW to the merchant Authorization Server.
| Question | Answer |
|---|---|
| Who creates it? | The merchant IAM administrator creates/registers the client representing AIGW. |
| Where do I get it? | From the merchant Authorization Server's client/application configuration. |
| What do I enter in AIGW? | The exact same Client ID configured at the merchant AS. |
| What is it used for? | Merchant AS client identification; with private_key_jwt, the AIGW client assertion uses the client identity when authenticating. |
Do not invent a second, unrelated Client ID in AIGW. The value must exactly match the client registered at the merchant authorization server.
3.5 Exchange & scopes (wizard step 3): identity providers and scopes
Identity providers (optional) determine how the human user can authenticate to AIGW for this Resource. Only providers enabled at the Account level are listed. The Resource's hosted screen is configured under Sign-in & consent. If the provider you need is unavailable, contact LoginID support. See Identity providers.
Each scope describes permission requested for the Resource.
| Scope field | What it is | Where it comes from / how to choose it | How it is used |
|---|---|---|---|
| Scope value | Protocol value such as search:read | Must align with permissions recognized by the merchant API/AS | Sent/represented as requested authorization |
| Display name | Human-readable permission name | Write for the user, not the protocol | Consent UI |
| Description | Explanation of what the permission allows | Write a concise, specific explanation | Consent UI when descriptions are enabled |
The merchant authorization server must recognize every scope value. A display name in AIGW does not create a merchant-side permission.
Click Create resource on step 3 to create the Resource and its signing key. Step 4 displays Reference values. If the wizard reports that the key could not be created, open Resource → Signing keys → New Signing Key. Confirm that a key is Active before configuring merchant trust. See Create and verify a signing key for Console and DevCLI steps.
4. Understand the Resource Reference screen
Save the Reference outputs: the merchant authorization server and agent integration need different values from this page. The same values stay available at the bottom of the Resource's Configuration tab. The page has two groups, each with Copy all:
For token exchange — hand these to whoever verifies subject tokens for this Resource (normally the merchant IAM team):
| AIGW output | What it is | What to do with it |
|---|---|---|
Expected aud of subject token | Configured merchant Issuer URL | Configure merchant JWT validation to accept this audience for AIGW user/client assertions; this is distinct from the Resource indicator |
client_id AIGW presents | The Client ID you entered | Must match the client registered at the merchant AS |
| Client authentication | Selected method, e.g. PRIVATE_KEY_JWT | Merchant AS client must be configured for the same method |
| Resource JWKS | https://api.aigw.loginid.ai/<RESOURCE_ID>/.well-known/jwks.json | Merchant AS verifies AIGW user and client assertions with these keys |
| Authorization server | Per-resource AIGW issuer, https://api.aigw.loginid.ai/<RESOURCE_ID> | Merchant IAM trusts it as the assertion issuer; MCP/UCP lists it in Protected Resource Metadata |
| Download oauth-protected-resource.json | Ready-made Protected Resource Metadata document | Starting point for your MCP/UCP /.well-known/oauth-protected-resource (see Protect your endpoint) |
For the agent — hand these to the agent developer:
| AIGW output | Value pattern |
|---|---|
| Token issuer and JWKS | Use issuer and jwks_uri from Resource discovery. These identify the shared core token issuer and its keys; use them to validate AIGW tokens |
| Discovery endpoint (OIDC) | https://api.aigw.loginid.ai/<RESOURCE_ID>/.well-known/openid-configuration |
| Discovery endpoint | https://api.aigw.loginid.ai/<RESOURCE_ID>/.well-known/oauth-authorization-server |
| OAuth2 authorization endpoint (GET) | https://api.aigw.loginid.ai/<RESOURCE_ID>/oauth2/auth |
| OAuth2 token endpoint (POST) | https://core.api.aigw.loginid.ai/oauth2/token (core, shared by all Resources) |
Active confirms Resource configuration, not a successful merchant-token exchange. Verify the integration through authorization, redemption, and an API call.
Merchant handoff package
If a different team or company operates the merchant IAM, send them at least:
AIGW per-resource issuer / Authorization Server URL
AIGW per-resource JWKS URL
AIGW Client ID configured for the merchant AS
Requested scope values
MCP Resource indicator
Selected grant/authentication method
They should use these values with the Merchant Authorization Server guide.
5. Create the MCP/UCP server credential
Open Project → Proxy clients → Generate new client.
A Proxy client authenticates your MCP/UCP backend to AIGW.
| AIGW output | What it is | Where to store it | How it is used |
|---|---|---|---|
| Proxy Client ID | OAuth client identifier for the MCP/UCP backend | Server configuration/secret store | Used with the secret in client_credentials |
| Proxy Client Secret | Secret proving the backend's identity | Secret manager; save immediately because the UI shows it once | Used to obtain a short-lived Proxy token |
| Proxy token | Returned later by AIGW's token endpoint | Backend memory/cache according to its lifetime | Sent as X-Proxy-Token when redeeming the merchant credential |
Example:
AIGW_PROXY_CLIENT_ID=...
AIGW_PROXY_CLIENT_SECRET=...
Never put these values in JavaScript shipped to a browser, and never return them to an agent.
6. Decide the agent policy
Open Project → Agents → Approval rules. A Project with no rules uses the system default, which approves every agent automatically. If you want to review new agents before they can reach the Resource, set Unverified agents (and any proof types you don't trust) to Hold; held agents appear under Agents → Pending. Resources can override the Project rules. See Agent policy.
7. Optional sign-in and consent configuration
Each Resource has a Sign-in & consent area.
These settings change the human authorization experience rather than the MCP/UCP HTTP protocol. Use them to control branding (logo, colors, border radius), the one-time-code fallback, scope descriptions, whether verified-agent information is shown, and the sign-in/consent screen text. See Identity providers.
The consent preview uses sample identity permissions. After saving, complete the sign-in and consent flow to verify the providers and scopes configured on your Resource. Allow one-time code fallback offers email-code sign-in when that method is available for your Account.
8. Pre-code verification checklist
Before writing MCP/UCP integration code, verify all handoffs:
| Check | Owner | Expected result |
|---|---|---|
| Resource exists in the intended Project | MCP/UCP operator | Correct Project/Resource visible in Console |
| Resource kind is Token exchange | MCP/UCP operator | Agent/MCP delegated-access model selected |
| Resource indicator is agreed | Merchant + MCP/UCP operator | Exact same value will be used during redemption |
| Issuer/token endpoint are correct | Merchant IAM | Point to the intended merchant AS/environment |
| AIGW Client ID matches merchant client | Merchant IAM + MCP/UCP operator | Same client identity on both sides |
| Authentication method is supported/configured | Merchant IAM + MCP/UCP operator | Both AIGW and merchant AS expect the same flow |
| Scope values exist on merchant side | Merchant IAM | Merchant AS/API recognizes them |
| Active signing key exists and is published in Resource JWKS | MCP/UCP operator | Matching kid in the key list and JWKS keys array |
| Merchant trusts AIGW issuer/JWKS | Merchant IAM | AIGW assertions can be verified |
| Proxy Client ID/Secret saved | MCP/UCP operator | Backend can obtain Proxy token |
| Agent policy matches intent | MCP/UCP operator | New agents are approved automatically or held for review, as intended |
Then continue to Protect your MCP / UCP endpoint.