360XView/mcp-auth-poc

MCP Authentication & Security Proof of Concept

Purpose: Test and validate authentication patterns for remote MCP servers before integrating into the main e2b2 learning platform.

🎯 Project Context

This PoC is part of the e2b2 intelligent learning platform project. The main platform uses MCP (Model Context Protocol) tools to deliver personalized coding education through Claude Desktop.

Why This PoC Exists:

• Validate token-based authentication for remote MCP servers
• Test development workflow with security enabled
• Understand Replit deployment process
• Provide a reference implementation for the main project
• Ensure authentication doesn't impede rapid development

Connection to Main Project:

• Main project location: ../v3/
• Main project uses 8 core MCP tools (see ../v3/docs/)
• This PoC validates the authentication layer that will wrap those tools
• Learnings from this PoC will be applied to the production architecture

📋 What This PoC Does

A minimal MCP server with:

• ✅ 2 simple tools (greeting generator and message echo)
• ✅ Token-based authentication (optional, can be disabled for development)
• ✅ SSE transport for remote connections
• ✅ User context injection (simulates student identification)
• ✅ Well-documented code (serves as example for main implementation)

🏗️ Architecture Overview

┌─────────────────┐
│  Claude Desktop │ (or OpenAI client)
└────────┬────────┘
         │ HTTP + Bearer Token
         ▼
┌─────────────────┐
│  Auth Middleware│ ◄── Validates token, extracts user
└────────┬────────┘
         │ Adds user context
         ▼
┌─────────────────┐
│   MCP Server    │ ◄── Tools receive authenticated user
└─────────────────┘
         │
         ▼
┌─────────────────┐
│  Tool Handlers  │ ◄── get_greeting, echo_message
└─────────────────┘

Key Design Decisions:

• Token-based auth (not OAuth) for simplicity in PoC
• Environment variable toggle for auth (easy local dev)
• User context passed to all tools (pattern for main project)
• Minimal dependencies (FastMCP, Uvicorn, python-dotenv)

📚 Documentation Structure

docs/
├── 01_CONTEXT.md              # Why this PoC exists, relationship to main project
├── 02_AUTHENTICATION.md       # Authentication architecture and decisions
├── 03_LOCAL_DEVELOPMENT.md    # Local setup and testing
├── 04_REPLIT_DEPLOYMENT.md    # Deploying to Replit
├── 05_CLIENT_SETUP.md         # Connecting Claude Desktop / OpenAI
└── 06_LESSONS_LEARNED.md      # Findings to apply to main project

🚀 Quick Start

Prerequisites

• Python 3.10+
• pip or uv package manager
• Claude Desktop (or OpenAI compatible client)

Local Development (No Auth)

# 1. Navigate to project
cd /path/to/v3_3_auth_and_sec

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run server
python server.py

Server runs at http://localhost:8000

Local Development (With Auth)

# 1. Create environment file
cp .env.example .env

# 2. Edit .env and set AUTH_ENABLED=true

# 3. Run server
python server.py

Testing the Tools

Option 1: Claude Desktop (see docs/05_CLIENT_SETUP.md)

{
  "mcpServers": {
    "auth-poc": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Option 2: MCP Inspector

npx @modelcontextprotocol/inspector python server.py

Option 3: Direct HTTP (with auth)

curl http://localhost:8000/tools \
  -H "Authorization: Bearer tok_test1_abc123"

📁 Project Structure

v3_3_auth_and_sec/
├── README.md                 # This file - project overview
├── requirements.txt          # Python dependencies
├── .env.example              # Example configuration
├── .env                      # Your local config (git-ignored)
├── .gitignore                # Ignore patterns
│
├── server.py                 # Main MCP server (well-documented)
├── auth_middleware.py        # Authentication logic (well-documented)
├── tools.py                  # Tool implementations (well-documented)
│
└── docs/                     # Comprehensive documentation
    ├── 01_CONTEXT.md
    ├── 02_AUTHENTICATION.md
    ├── 03_LOCAL_DEVELOPMENT.md
    ├── 04_REPLIT_DEPLOYMENT.md
    ├── 05_CLIENT_SETUP.md
    └── 06_LESSONS_LEARNED.md

🔑 Authentication Flow

sequenceDiagram
    participant Client as Claude Desktop
    participant Middleware as Auth Middleware
    participant Server as MCP Server
    participant Tool as Tool Handler

    Client->>Middleware: Request + Bearer Token
    Middleware->>Middleware: Validate Token
    Middleware->>Middleware: Extract User Info
    Middleware->>Server: Request + User Context
    Server->>Tool: Execute with User
    Tool-->>Client: Response with User Data

🧪 Testing Checklist

• Local server runs without auth
• Local server runs with auth enabled
• Claude Desktop connects locally (no auth)
• Claude Desktop connects locally (with auth)
• Deploy to Replit successfully
• Claude Desktop connects to Replit (with auth)
• Multiple users can connect with different tokens
• Invalid tokens are rejected with clear errors

📖 Key Files to Understand

1. server.py - Entry point, shows how FastMCP + auth middleware integrate
2. auth_middleware.py - Core authentication logic, user extraction
3. tools.py - Example tools that use user context
4. docs/02_AUTHENTICATION.md - Deep dive on authentication architecture

🎓 Learning Objectives

After working through this PoC, you should understand:

• ✅ How to add authentication to FastMCP servers
• ✅ How to toggle auth for development vs production
• ✅ How to inject user context into MCP tool handlers
• ✅ How to deploy authenticated MCP servers to Replit
• ✅ How to connect remote authenticated servers to Claude Desktop
• ✅ Patterns to apply to the main e2b2 platform

🔄 Next Steps After PoC

1. Validate locally - Ensure auth works as expected
2. Deploy to Replit - Test remote authentication
3. Document learnings - Update docs/06_LESSONS_LEARNED.md
4. Apply to main project - Integrate patterns into ../v3/

🤝 Development Notes

Code Style:

• Comprehensive docstrings on all functions
• Inline comments for complex logic
• Type hints for clarity
• Clear variable names

This code is intentionally over-documented to serve as a reference for the main project implementation.

🔗 Related Documentation

• Main Project: ../v3/README.md
• MCP Specification: https://modelcontextprotocol.io
• FastMCP Docs: https://github.com/jlowin/fastmcp
• Replit Docs: https://docs.replit.com

📞 Questions?

If you encounter issues:

1. Check the relevant doc in docs/
2. Review code comments in the .py files
3. Consult docs/06_LESSONS_LEARNED.md for known issues
4. Refer back to the main project's architecture docs

Project Status: PoC Phase Last Updated: 2025-10-11 Main Project: e2b2 Learning Platform (../v3/)