# 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)

```bash
# 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)

```bash
# 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`)
```json
{
  "mcpServers": {
    "auth-poc": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}
```

**Option 2: MCP Inspector**
```bash
npx @modelcontextprotocol/inspector python server.py
```

**Option 3: Direct HTTP (with auth)**
```bash
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

```mermaid
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/`)