Model Context Protocol (MCP) Server Example Using OAuth2.1 and AWS Cognito

Overview: What is the Model Context Protocol (MCP) Server?

The Model Context Protocol (MCP) server example integrates MCP with OAuth 2.1 to secure resources for AI applications such as Claude Desktop, Continue, Cursor, and others. This documentation provides a comprehensive guide on how to set up an MCP server that acts as a Resource Server (RS) and is secured through the OAuth 2.1 Authorization Code Flow with PKCE using AWS Cognito.

🔧 Core Features & MCP Capabilities

The core features of this MCP server implementation include:

• MCP Integration: Acts as an RS, ensuring seamless integration for AI applications via MCP.
• OAuth 2.1 Security: Secures the resource endpoints using OAuth 2.1 standards with PKCE (Proof Key for Code Exchange) support.
• PRM Document Discovery: Dynamically discovers the protected resource metadata document from the authorization server.
• Dynamic Authorization Metadata Discovery: Automatically retrieves and adapts to changing configurations of the authorization server.

⚙️ MCP Architecture & Protocol Implementation

The architecture overview involves a client making an unsecured request, which then leads through a series of OAuth 2.1 flows:

1. Client Request Without Token

   • The unauthorized client makes its first request.

2. 401 Unauthorized with WWW-Authenticate Header

   • MCP server responds with a 401 status and a WWW-Authenticate header pointing to PRM metadata.

3. PRM Metadata Discovery

   • Client retrieves the PRM document, discovering the Authorization Server’s URL.

4. Authorization Code Flow with PKCE

   • Client initiates an OAuth 2.1 Authorization Code flow against AWS Cognito, completing with PKCE for added security.

5. Access Token Retrieval and Retry Request

   • After obtaining a valid access token, the client retries its initial request to the MCP server.

6. Token Validation and Access Granting

   • MCP server validates the token and grants access to the protected resource.

Mermaid Diagram for Protocol Flow

graph TD
    A[Client] -->|Request| B[MCP Server]
    B --> C[401 Unauthorized with WWW-Authenticate]
    C --> D[Fetch PRM Metadata]
    D --> E[AWS Cognito URL Discovery]
    E --> F[OAuth 2.1 Authorization Code Flow (PKCE)]
    F --> G[Receive Access Token]
    G --> H[Rerun Request to MCP Server]
    H --> I[MCP Server Validation and Access]

Mermaid Diagram for Data Architecture

graph TD
    A[Client] --> B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8

🚀 Getting Started with Installation

1. AWS Cognito Setup

• Create a New Cognito User Pool
• Set Up App Client:
  • Enable OAuth 2.0 Authorization Code grant flow.
  • Enable PKCE.
  • Set callback URL (e.g., http://localhost:3000/callback).
• Enable OpenID Connect Scopes:
  • openid
  • profile
  • email

2. MCP Server

• Run the MCP Server Locally: Ensure it serves a .well-known/oauth-protected-resource endpoint with links to Cognito’s Authorization Server.

3. Client

• Run the Example Client:
  • It will perform OAuth 2.1 discovery steps, handle PKCE, and process tokens for accessing protected endpoints.

💡 Key Use Cases in AI Workflows

Use Case: Interactive Data Exploration

1. Scenario: An AI-driven data analysis application uses MCP to connect with various datasets.
2. Process:
   • MCP Setup: The application uses an MCP server to interact with multiple data sources securely.
   • Data Access: Upon receiving a valid token, the application can query and analyze the data seamlessly.

Use Case: Custom Prompt Generation

1. Scenario: A personalized AI chatbot uses MCP to fetch user-specific context from external tools.
2. Process:
   • OAuth Integration: The MCP server handles authentication and token acquisition.
   • Token Usage: Upon receiving a token, the application can dynamically generate or retrieve contextual responses.

🔌 Integration with MCP Clients

The clients include:

• Claude Desktop: Full support for MCP integration.
• Continue: Fully compatible.
• Cursor: Supports tools but not all features.

MCP Client Compatibility Matrix

MCP Client	Resources	Tools	Prompts
Claude Desktop	✅	✅	✅
Continue	✅	✅	✅
Cursor	❌	✅	❌

📊 Performance & Compatibility Matrix

The implementation ensures optimal performance and compatibility across different AI applications, while leveraging OAuth 2.1 for secure token management.

🛠️ Advanced Configuration & Security

To configure the server:

{
  "mcpServers": {
    "[server-name]": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-[name]"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Security Considerations

1. PKCE Implementation: Ensures secure token exchanges.
2. OAuth 2.1 Compliance: Adheres to current OAuth standards.

❓ Frequently Asked Questions (FAQ)

1. Q: Can I use this MCP server with any AI application?

   • A: Yes, this implementation is compatible with Claude Desktop and Continue out of the box.

2. Q: How does PKCE enhance security?

   • A: PKCE adds a layer of security by ensuring that the Authorization Code cannot be intercepted during transmission.

3. Q: Can I integrate third-party authentication providers like Okta or Auth0?

   • A: Currently, only AWS Cognito is supported. However, multi-provider support is being considered for future releases.

4. Q: How do I handle dynamic client registration with MCP servers?

   • A: Dynamic Client Registration (DCR) may be supported in the near future based on technical feasibility.

5. Q: Can this server be deployed without Node.js or C#.NET 8 environments?

   • A: The implementation is currently tailored for these environments, but other languages could be adapted with modifications.

👨‍💻 Development & Contribution Guidelines

Contributions from the community are highly encouraged. Follow our contribution guidelines to get started.

🌐 MCP Ecosystem & Resources

Explore further by visiting:

• Official MCP Specification: https://modelcontextprotocol.io/specification/draft/basic/authorization
• OAuth 2.1 Draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12
• AWS Cognito Developer Guide: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html

License

This project is licensed under the MIT License.

---

Conclusion

By following this comprehensive guide, developers can integrate and secure their AI applications with MCP through OAuth 2.1 and AWS Cognito. This implementation not only ensures robust security measures but also facilitates seamless interaction between various AI tools and data resources.