# Connect to Managed Amazon Agent Iris

Canonical page: https://www.kuudo.com/docs/managed-mcp/iris/


Connect an MCP-compatible AI client to managed Amazon Agent Iris at `https://iris.kuudo.com/mcp` using Kuudo OAuth. Iris helps create, edit and review images and video. Google-backed generation needs a separate Google Gemini API key; the provider credential does not replace your Kuudo sign-in.

> **Verification note:** OAuth discovery is available, but an authenticated connection and Google-backed generation using this header have not been verified for the deployed Iris service. Check client support and confirm the setup before relying on it.

## Endpoints and authentication

| Purpose                             | Address or header                                                 |
| ----------------------------------- | ----------------------------------------------------------------- |
| MCP server                          | `https://iris.kuudo.com/mcp`                                      |
| OAuth resource discovery            | `https://iris.kuudo.com/.well-known/oauth-protected-resource/mcp` |
| Kuudo sign-in issuer                | `https://app.kuudo.com`                                           |
| Google generation credential header | `X-API-Token`                                                     |

Add the **MCP server** address to your client. The other addresses are used for OAuth discovery; you normally do not enter them manually.

Use OAuth with your **Kuudo user account** to connect to Iris, approving the `mcp:access` permission when prompted. Your MCP client handles the OAuth bearer token. For Google-backed generation, configure the separate **`X-API-Token`** connection header with your raw Gemini API key. `X-API-Token` is a Google-only alias for `X-Google-API-Key` in Iris source; it is not a Kuudo API key or the OAuth bearer token. The deployed version and provider-header behavior still need verification.

```http
Authorization: Bearer <KUUDO_OAUTH_ACCESS_TOKEN>
X-API-Token: <GOOGLE_GEMINI_API_KEY>
```

The example shows what the client sends. Let the client manage the `Authorization` header for OAuth; configure `X-API-Token` separately as a custom header. Do not add `Bearer` to the Google key or put a key in a prompt or tool argument. The alias is for Google credentials, not OpenAI credentials.

## Before you connect

- Have a Kuudo user account and membership in the intended organization.
- For Google image or video generation, [get a Google Gemini API key for Iris](/docs/amazon-agent-iris/google-api-key/). The associated Google project needs access to the requested model and any required quota or billing.
- Use an MCP client that supports **both** Kuudo OAuth and a custom connection header. It must send the custom header on subsequent MCP requests as well as the initial connection.
- Store the key using the client's secret facilities. Do not share it, commit it to a repository, or place it in a prompt.

An operator may configure a server-side Google credential. If you do not supply your own header, ask the operator whether a fallback is available. An explicitly invalid or rejected key does not switch to a fallback.

## Connect your AI client

1. In the client, add a remote MCP server or custom connector.
2. Enter `https://iris.kuudo.com/mcp` as the server URL.
3. In the connection's custom headers, set **`X-API-Token`** to your raw Google Gemini API key.
4. Start the connection. When prompted, sign in with your Kuudo user account, select the intended organization if asked, and approve the requested access.
5. Confirm the client lists Iris tools. Try a simple image request, such as: “Create a product image concept on a neutral background.” Review the result before using it in an Amazon listing or advertisement.

If your client cannot combine OAuth with custom headers, use a compatible client or ask the Iris operator whether a server-side Google credential is available. Do not replace the Kuudo OAuth bearer with the Google key.

## OAuth client requirements

Kuudo supports OAuth authorization code with PKCE and client ID metadata documents (CIMD), as well as appropriately preregistered clients. A client that supports only dynamic client registration needs an appropriate Kuudo registration. Client support for OAuth and custom headers varies.

## Troubleshooting

- **Kuudo sign-in fails:** Check the server URL, client OAuth compatibility, and selected Kuudo organization. The Google key cannot sign you in to Iris.
- **Tools appear but Google generation fails:** Check that `X-API-Token` is present on the connection and subsequent requests, contains the raw Gemini key, and is valid for the Google project, model, quota, and billing. A successful MCP connection does not prove the Google credential works.
- **Your client cannot add the header:** Use a compatible client or ask the operator about a configured server fallback.
- **A long-running video task cannot continue:** Keep the same Google credential available for the follow-up requests and check the client's connection settings.

If you need help, share the client name, time, and error message with support; do not share your Kuudo token or provider API key.