Copy page

MCP Authorization

MCP Amazon Cognito OAuth Policy

Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Amazon Cognito.

This is a Cognito-friendly wrapper around McpOAuthInboundPolicy. Provide an AWS region, user pool ID, hosted UI domain, clientId, and clientSecret; the Cognito OIDC issuer, JWKS URL, and browser login endpoints are derived automatically.

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

config/policies.json
{
  "name": "my-mcp-cognito-oauth-inbound-policy",
  "policyType": "mcp-cognito-oauth-inbound",
  "handler": {
    "export": "McpCognitoOAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "awsRegion": "us-east-1",
      "browserLoginOverrides": {
        "remoteTimeoutMs": 10000,
        "sessionTtlSeconds": 28800,
        "stateTtlSeconds": 900
      },
      "clientId": "$env(COGNITO_CLIENT_ID)",
      "clientSecret": "$env(COGNITO_CLIENT_SECRET)",
      "gateway": {
        "accessTokenTtlSeconds": 900,
        "cimdEnabled": true,
        "refreshTokenTtlSeconds": 2592000
      },
      "scope": "openid profile email",
      "userPoolDomain": "auth.example.com",
      "userPoolId": "us-east-1_AbCdEf123"
    }
  }
}

Policy Configuration

• name <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be mcp-cognito-oauth-inbound.
• handler.export <string> - The name of the exported type. Value should be McpCognitoOAuthInboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

• awsRegion (required) <string> - The AWS region that contains the Amazon Cognito user pool.
• userPoolId (required) <string> - The Amazon Cognito user pool ID.
• userPoolDomain (required) <string> - The hosted UI domain for the user pool, without https://, a trailing slash, or a path.
• clientId (required) <string> - The Cognito app client_id registered for the gateway's browser login flow.
• clientSecret (required) <string> - The Cognito app client_secret. Use $env(...) to source from a secret environment variable.
• scope <string> - OIDC scopes requested during browser login. Defaults to "openid profile email".
• gateway <object> - Gateway-side OAuth token settings. The gateway issuer and advertised URLs are derived from the incoming request origin.
  • accessTokenTtlSeconds <integer> - Lifetime of access tokens issued by /oauth/token. Defaults to 900.
  • refreshTokenTtlSeconds <integer> - Lifetime of refresh tokens issued by /oauth/token. Defaults to 2592000.
  • cimdEnabled <boolean> - Whether to advertise client_id_metadata_document_supported in AS metadata. Defaults to true.
• browserLoginOverrides <object> - Optional overrides for the derived browser-login settings.
  • remoteTimeoutMs <integer> - No description available. Defaults to 10000.
  • stateTtlSeconds <integer> - No description available. Defaults to 900.
  • sessionTtlSeconds <integer> - No description available. Defaults to 28800.

Using the Policy

MCP Amazon Cognito OAuth Inbound

Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Amazon Cognito.

This is a thin Cognito-friendly wrapper around the generic McpOAuthInboundPolicy. Use it when you want to configure browser login with Cognito user pool fields instead of the full set of OIDC URLs.

Derived configuration

Given an AWS region, user pool ID, and user pool hosted UI domain, the wrapper derives:

Generic field	Derived value
oidc.issuer	https://cognito-idp.{awsRegion}.amazonaws.com/{userPoolId}
oidc.jwksUrl	https://cognito-idp.{awsRegion}.amazonaws.com/{userPoolId}/.well-known/jwks.json
browserLogin.url	https://{userPoolDomain}/oauth2/authorize
browserLogin.tokenUrl	https://{userPoolDomain}/oauth2/token

Amazon Cognito hosts the discovery and JWKS documents on the Cognito IDP service domain, while browser login endpoints are served from the user pool domain.

Configuration

Code
{
  "name": "cognito-managed-oauth",
  "policyType": "mcp-cognito-oauth-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime)",
    "export": "McpCognitoOAuthInboundPolicy",
    "options": {
      "awsRegion": "us-east-1",
      "userPoolId": "us-east-1_AbCdEf123",
      "userPoolDomain": "auth.example.com",
      "clientId": "$env(COGNITO_CLIENT_ID)",
      "clientSecret": "$env(COGNITO_CLIENT_SECRET)"
    }
  }
}

userPoolDomain must be the hosted UI host name only. Do not include https://, a trailing slash, or an OAuth path.

Pairing

Pair this policy with McpTokenExchangeInboundPolicy and McpProxyHandler, the same as McpOAuthInboundPolicy. Only one MCP OAuth policy is allowed per project; attach the same policy by name to every MCP route.

Read more about how policies work