AWS Cognito OAuth

FastMCP v2.14.5

Meet Prefect Horizon, the enterprise MCP gateway built by the team behind FastMCP.

These are the docs for FastMCP 2.0. FastMCP 3.0 is now available.

Configuration

Prerequisites

Before you begin, you will need:

1. An AWS Account with access to create AWS Cognito user pools.
2. Basic familiarity with AWS Cognito concepts (user pools, app clients).
3. Your FastMCP server’s URL (can be localhost for development, e.g., http://localhost:8000).

Step 1: Create an AWS Cognito User Pool and App Client

Set up AWS Cognito user pool with an app client to get the credentials needed for authentication:

1. Go to the AWS Cognito Console and ensure you’re in your desired AWS region.
2. Select “User pools” from the side navigation and click “Create user pool” to create a new user pool.

Define Your Application:

• Application type: Select “Traditional web application” (this is the correct choice for FastMCP server-side authentication).
• Name your application: Enter a descriptive name (e.g., FastMCP Server).

Configure Options:

• Sign-in identifiers: Choose how users will sign in (email, username, or phone).
• Required attributes: Select any additional user information you need.
• Return URL: Add your callback URL (e.g., http://localhost:8000/auth/callback for development).

Step 2: FastMCP Configuration

Create your FastMCP server using the AWSCognitoProvider, which handles AWS Cognito’s JWT tokens and user claims automatically:

from fastmcp import FastMCP
from fastmcp.server.auth.providers.aws import AWSCognitoProvider
from fastmcp.server.dependencies import get_access_token

auth_provider = AWSCognitoProvider(
    user_pool_id="eu-central-1_XXXXXXXXX",
    aws_region="eu-central-1",
    client_id="your-app-client-id",
    client_secret="your-app-client-secret",
    base_url="http://localhost:8000",
)

mcp = FastMCP(name="AWS Cognito Secured App", auth=auth_provider)

@mcp.tool
async def get_access_token_claims() -> dict:
    """Get the authenticated user's access token claims."""
    token = get_access_token()
    return {
        "sub": token.claims.get("sub"),
        "username": token.claims.get("username"),
        "cognito:groups": token.claims.get("cognito:groups", []),
    }

Testing

Running the Server

Start your FastMCP server with HTTP transport to enable OAuth flows:

fastmcp run server.py --transport http --port 8000

Testing with a Client

Create a test client that authenticates with Your AWS Cognito-protected server:

from fastmcp import Client
import asyncio

async def main():
    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
        print("✓ Authenticated with AWS Cognito!")

print("Calling protected tool: get_access_token_claims")
        result = await client.call_tool("get_access_token_claims")
        user_data = result.data
        print("Available access token claims:")
        print(f"- sub: {user_data.get('sub', 'N/A')}")
        print(f"- username: {user_data.get('username', 'N/A')}")
        print(f"- cognito:groups: {user_data.get('cognito:groups', [])}")

if __name__ == "__main__":
    asyncio.run(main())

Production Configuration

For production deployments, ensure to configure jwt_signing_key, and client_storage:

import os
from fastmcp import FastMCP
from fastmcp.server.auth.providers.aws import AWSCognitoProvider

auth_provider = AWSCognitoProvider(
    user_pool_id="eu-central-1_XXXXXXXXX",
    aws_region="eu-central-1",
    client_id="your-app-client-id",
    client_secret="your-app-client-secret",
    base_url="https://your-production-domain.com",
)

mcp = FastMCP(name="Production AWS Cognito App", auth=auth_provider)

Features

JWT Token Validation

The AWS Cognito provider includes robust JWT token validation:

• Signature Verification: Validates tokens against AWS Cognito’s public keys (JWKS).
• Expiration Checking: Automatically rejects expired tokens.
• Issuer Validation: Ensures tokens come from your specific AWS Cognito user pool.
• Scope Enforcement: Verifies required OAuth scopes are present.

User Claims and Groups

Access rich user information from AWS Cognito JWT tokens:

@mcp.tool
async def admin_only_tool() -> str:
    token = get_access_token()
    user_groups = token.claims.get("cognito:groups", [])

if "admin" not in user_groups:
        raise ValueError("This tool requires admin access")

return "Admin access granted!"

Enterprise Integration

Perfect for enterprise environments with:

• Single Sign-On (SSO): Integrate with corporate identity providers.
• Multi-Factor Authentication (MFA): Leverage AWS Cognito’s built-in MFA.
• User Groups: Role-based access control through AWS Cognito groups.
• Custom Attributes: Access custom user attributes defined in your AWS Cognito user pool.
• Compliance: Meet enterprise security and compliance requirements.