merged with main

Author: aarora79

.gitignore

@@ -132,6 +132,8 @@ celerybeat.pid
 
 # Environments
 .env
+.env.user
+.env.agent
 .env.docker
 .venv
 env/

README.md

@@ -148,6 +148,7 @@ flowchart TB
 *   An Amazon EC2 machine (`ml.t3.2xlarge`) with a standard Ubuntu AMI for running this solution.
 *   An SSL cert for securing the communication to the Gateway. _This Gateway uses a self-signed cert by default and is also available over HTTP_. 
 *   One of the example MCP servers packaged in this repo uses the [`Polygon`](https://polygon.io/stocks) API for stock ticker data. Get an API key from [here](https://polygon.io/dashboard/signup?redirect=%2Fdashboard%2Fkeys). The server will still start without the API key but you will get a 401 Unauthorized error when using the tools provided by this server.
+*   Setup authentication using Amazon Cognito as per instructions [here](docs/auth.md).
 
 ## Installation
 
@@ -361,11 +362,9 @@ See the full API spec [here](docs/registry_api.md).
 ## Roadmap
 
 1. Store the server information in persistent storage.
-1. Add OAUTH 2.1 support to Gateway and Registry.
 1. Use GitHub API to retrieve information (license, programming language etc.) about MCP servers.
 1. Add option to deploy MCP servers.
 
 ## License
 
-- Free for non-commercial use under AGPL-3.0
-- Commercial use requires a paid license
+This project is licensed under the Apache-2.0 License.

agents/.env.template

@@ -11,4 +11,12 @@ COGNITO_CLIENT_SECRET=your_cognito_client_secret_here
 COGNITO_USER_POOL_ID=your_cognito_user_pool_id_here
 
 # AWS Region for Cognito
-AWS_REGION=us-east-1
+AWS_REGION=us-east-1
+
+# Cognito Domain (without https:// prefix, just the domain name)
+# Example: mcp-gateway or your-custom-domain
+# COGNITO_DOMAIN=
+
+# Secret key for session cookie signing (must match registry SECRET_KEY), string of hex characters
+# To generate: python -c 'import secrets; print(secrets.token_hex(32))'
+SECRET_KEY=your-secret-key-here

agents/agent_w_auth.py

@@ -163,17 +163,13 @@ def load_env_config(use_session_cookie: bool) -> Dict[str, Optional[str]]:
             if os.path.exists(env_file):
                 logger.info(f"Found .env file in parent directory: {env_file}")
                 load_dotenv(env_file, override=True)
-                file_found = True
-                file_path = env_file
                 logger.info(f"Loading environment variables from {env_file}")
             else:
                 # Try to load from current working directory
                 env_file = os.path.join(os.getcwd(), env_file_name)
                 if os.path.exists(env_file):
                     logger.info(f"Found .env file in current working directory: {env_file}")
                     load_dotenv(env_file, override=True)
-                    file_found = True
-                    file_path = env_file
                     logger.info(f"Loading environment variables from {env_file}")
                 else:
                     # Fallback to default .env loading

auth_server/.env.template

@@ -0,0 +1,28 @@
+# Cognito Authentication Configuration
+# Copy this file to .env and fill in your actual values
+
+# Auth Server URL
+AUTH_SERVER_URL=http://localhost:8888
+
+# Cognito App Client ID
+COGNITO_CLIENT_ID=your_cognito_client_id_here
+
+# Cognito App Client Secret
+COGNITO_CLIENT_SECRET=your_cognito_client_secret_here
+
+# Cognito User Pool ID
+COGNITO_USER_POOL_ID=your_cognito_user_pool_id_here
+
+# Cognito Domain (without https:// prefix, just the domain name)
+# Example: mcp-gateway or your-custom-domain
+COGNITO_DOMAIN=your_cognito_domain_here
+
+# Secret key for session cookie signing (must match registry SECRET_KEY)
+# Generate a secure random string for production use
+# To generate: python -c 'import secrets; print(secrets.token_hex(32))'
+SECRET_KEY=your-secret-key-here
+
+USER_POOL_ID=your_cognito_user_pool_id_here
+
+# AWS Region for Cognito
+AWS_REGION=us-east-1

auth_server/scopes.yml

@@ -289,4 +289,3 @@ mcp-servers-restricted/execute:
       - user_profile_analyzer
       - synthetic_data_generator
 
-

auth_server/server.py

@@ -644,6 +644,7 @@ async def validate_request(request: Request):
             if cookie_value:
                 try:
                     validation_result = validate_session_cookie(cookie_value)
+                    logger.info(f"Session cookie validation result: {validation_result}")
                     logger.info(f"Session cookie validation successful for user: {validation_result['username']}")
                 except ValueError as e:
                     logger.warning(f"Session cookie validation failed: {e}")

docs/auth.md

@@ -168,16 +168,16 @@ The above implementation provides an OAuth compliant way to MCP security without
 
 This section discusses the reference implementation using Amazon Cognito as the IdP, supporting both Machine-to-Machine (M2M) and Session Cookie authentication methods.
 
+>This section will soon be updated with detailed steps for Cognito configuration.
+
 ### Key Components
 
 #### 1. Auth Server (`auth_server/server.py`)
-The enhanced auth server provides dual authentication support:
+The auth server provides dual authentication support:
 - **Primary Check**: Session cookie validation using `itsdangerous.URLSafeTimedSerializer`
 - **Fallback**: JWT token validation with Cognito
-- **Group Mapping**: Maps Cognito groups to MCP scopes
-  - `mcp-admin` → Full unrestricted access
-  - `mcp-user` → Restricted read access
-  - `mcp-server-*` → Server-specific execute access
+- **Group Mapping**: Maps Cognito groups to MCP scopes via `scopes.yml` configuration
+  - Both M2M and session cookie auth use the same scope definitions
 
 #### 2. CLI Authentication Tool (`auth_server/cli_auth.py`)
 A standalone tool for user-based authentication:
@@ -204,12 +204,17 @@ Cognito supports machine-to-machine authentication, enabling Agents to have thei
 - MCP Server(s) function as resource servers
 
 #### Authentication Flow:
+Run the Agent with the following command:
+```{.bash}
+python agents/agent_w_auth.py
+```
+1. Copy `agents/.env.template` to `agents/.env.agent` and set the environment variables (`COGNITO_CLIENT_ID`, `COGNITO_CLIENT_SECRET`, `COGNITO_USER_POOL_ID`) as appropriate for your setup.
 1. Agent startup:
-   - Configured with client ID, client secret, and a set of scopes
+   - Configured with client ID, client secret, and a set of scopes. _Each agent is an App Client in a Cognito user pool_.
    - Requests scopes (e.g., MCP Registry with tool finder and basic MCP servers)
-2. Cognito issues a JWT token
-3. Agent includes the JWT token in MCP headers
-4. Auth server on Nginx side:
+1. Cognito issues a JWT token
+1. Agent includes the JWT token in MCP headers
+1. Auth server on Nginx side:
    - Retrieves JWT token
    - Calls Cognito to validate token and get allowed scopes
    - Returns 200 or 403 based on:
@@ -219,10 +224,10 @@ Cognito supports machine-to-machine authentication, enabling Agents to have thei
 
 #### Advantages
 1. Leverages existing Cognito user identities and groups
-2. No need to manage separate M2M credentials for user-initiated actions
-3. Maintains user context throughout the session
-4. Compatible with existing web-based authentication flow
-5. Auth server handles both authentication methods transparently
+1. No need to manage separate M2M credentials for user-initiated actions
+1. Maintains user context throughout the session
+1. Compatible with existing web-based authentication flow
+1. Auth server handles both authentication methods transparently
 
 ### 2. Session Cookie Authentication
 
@@ -236,8 +241,7 @@ The CLI tool handles the OAuth flow with Cognito and saves the session cookie lo
 
 ```bash
 # Run the CLI authentication tool
-cd auth_server
-python cli_auth.py
+python agents/cli_auth.py
 
 # This will:
 # 1. Open your browser to Cognito hosted UI
@@ -247,13 +251,15 @@ python cli_auth.py
 ```
 
 Required environment variables:
-- `COGNITO_DOMAIN`: Your Cognito domain (e.g., 'mcp-gateway')
+- `COGNITO_USER_POOL_ID`: Your Cognito user pool id 
 - `COGNITO_CLIENT_ID`: OAuth client ID configured for PKCE flow
 - `SECRET_KEY`: Must match the registry's SECRET_KEY for cookie compatibility
 
 ##### b. Agent with Session Cookie Support
 
-The enhanced agent (`agents/agent_w_auth.py`) now supports session cookie authentication:
+Copy `agents/.env.template` to `agents/.env.user` and set the environment variables (`COGNITO_CLIENT_ID`, `COGNITO_CLIENT_SECRET`, `COGNITO_USER_POOL_ID`, `SECRET_KEY`) as appropriate for your setup.
+
+The agent (`agents/agent_w_auth.py`) supports session cookie authentication:
 
 ```bash
 # Use agent with session cookie
@@ -269,15 +275,14 @@ Key features:
 - Automatically reads cookie and includes in request headers
 - Falls back to M2M if session cookie flag not provided
 
-##### c. Auth Server Enhancements
+##### c. Auth Server
 
 The auth server validates session cookies alongside JWT tokens:
 - Checks for `mcp_gateway_session` cookie in request headers
 - Validates cookie signature using `itsdangerous.URLSafeTimedSerializer`
-- Maps Cognito groups to MCP scopes:
-  - `mcp-admin` → unrestricted read/execute access
-  - `mcp-user` → restricted read access
-  - `mcp-server-{name}` → server-specific execute access
+- Maps Cognito groups to MCP scopes using `scopes.yml` configuration:
+  - Configuration-driven mapping ensures consistency with M2M authentication
+  - Single source of truth for all permission definitions
 - Falls back to JWT validation if no valid cookie found
 
 #### Advantages: