MCP 服务器

mcp-auth-poc

A minimal MCP server with token-based authentication and SSE transport, providing greeting and echo tools for testing authentication patterns in remote MCP servers.

README

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