MCP-Tools mit OAuth-Authentifizierung

Ein Python-Beispiel, das zeigt, wie ein MCP-Server (Model Context Protocol) mit OAuth-Authentifizierung aufgebaut wird und dabei einen API-Client, eine Geschäftslogikschicht und abgesicherte MCP-Tools kombiniert.

Merkmale

• OAuth-Authentifizierungsablauf: Authentifizierung per Klick im Browser für Sitzungstokens

• Mehrschichtige Architektur: API-Client → Geschäftslogik → MCP-Tools

• Sicherer Tool-Zugriff: Erfordert ein gültiges Auth-Token zum Aufrufen geschützter Tools

• Einfacher HTTP-Server: Flask-basierter Authentifizierungsserver unter localhost:5000

• Token-Verwaltung: 24 Stunden gültige Sitzungstokens mit Persistenz

Related MCP server: OAuth MCP Server

Architektur

src/example/
├── api/
│   ├── api_client.py      # HTTP API client (JSONPlaceholder)
│   └── http_server.py     # Local HTTP server
├── auth/
│   └── manager.py         # OAuth token & state management
├── business/
│   └── service.py         # Business logic layer
├── http/
│   └── auth_server.py     # Flask OAuth auth server
├── mcp/
│   └── server.py          # MCP server with auth
└── main.py

Installation

python -m venv .venv

# Windows:
.venv\Scripts\activate

# Linux/macOS:
source .venv/bin/activate

pip install -r requirements.txt

Schnellstart

1. Authentifizierungsserver starten

python -m src.example.http.auth_server

Dadurch wird ein Flask-Server mit einem OAuth-Ablauf unter http://localhost:5000 gestartet:

• Rufen Sie die Startseite auf

• Klicken Sie auf „Klicken zum Authentifizieren“

• Erhalten Sie Ihr Sitzungstoken auf der Rückrufseite

• Kopieren und speichern Sie Ihr Token

2. MCP-Server starten

In einem anderen Terminal:

python -m src.example.mcp.server

3. MCP-Tools verwenden

Der MCP-Server erfordert nun eine Authentifizierung. Rufen Sie zuerst die Authentifizierungs-URL ab:

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python -m src.example.mcp.server

Authentifizieren Sie sich anschließend und verwenden Sie die Tools mit Ihrem Token:

echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_user","arguments":{"user_id":1},"auth_token":"YOUR_SESSION_TOKEN"},"id":1}' | python -m src.example.mcp.server

Authentifizierungsablauf

1. Authentifizierungs-URL abrufen: Rufen Sie das Tool get_auth_url auf (keine Authentifizierung erforderlich)

   {"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_auth_url","arguments":{}},"id":1}

2. Im Browser klicken: Der Benutzer klickt auf die zurückgegebene Authentifizierungs-URL

   • Öffnet http://localhost:5000/auth/callback?state=...

   • Der Browser zeigt eine Erfolgsseite mit dem Sitzungstoken

   • Das Token ist 24 Stunden gültig

3. Token verwenden: Geben Sie auth_token bei allen Tool-Aufrufen mit

   {"params":{"name":"get_user","arguments":{"user_id":1},"auth_token":"YOUR_TOKEN"}}

Verfügbare Tools

Öffentlich (keine Authentifizierung erforderlich)

• get_auth_url - OAuth-Authentifizierungs-URL abrufen

Geschützt (Authentifizierung erforderlich)

• get_user - Einen Benutzer anhand der ID abrufen

• list_users - Alle Benutzer auflisten

• create_user - Einen neuen Benutzer erstellen

• update_user - Benutzername/E-Mail aktualisieren

• delete_user - Einen Benutzer löschen

Konfiguration

Legen Sie die Umgebungsvariablen fest:

export PORT=5000                           # Auth server port
export FLASK_SECRET_KEY=your-secret-key    # Flask secret (change in production!)

Tests

Führen Sie die Tests mit pytest aus:

pytest -v
pytest --cov=src           # With coverage
pytest tests/test_auth.py  # Auth tests only

Shell-Skript ausführen

sh test-auth-flow.sh
========================================
  MCP Auth Server - Complete Flow Test
========================================
Base URL: https://claude-ia-mcp-tools-auth-staging.up.railway.app

Step 1: Start Auth Flow
GET /auth/start
Status: 401
Auth URL: https://claude-ia-mcp-tools-auth-staging.up.railway.app/auth/callback?state=Xukdt6MwHba0n0UfkOX3lAAanm7MJhSyzomyCJCxj1M

State Token: Xukdt6MwHba0n0UfkOX3lAAanm7MJhSyzomyCJCx...

Step 2: Complete Auth Callback
GET /auth/callback?state=Xukdt6MwHba0n0UfkOX3lAAanm7MJhSyzomyCJCxj1M
Status: 200
Session Token: 7Y6SaanfrLmiOXoE2kUvTbdEfawIMSJyGDaNFPf1...

Step 3: Verify Token with Auth Status
GET /auth/status -H 'Authorization: Bearer 7Y6SaanfrLmiOXoE2kUvTbdEfawIMSJyGDaNFPf1-Bg'
Response:
{"authenticated":true,"user_id":"user_1b25e4982c9904b8"}

========================================
         TEST RESULTS
========================================
State Token:     Xukdt6MwHba0n0UfkOX3lAAanm7MJhSyzomyCJCxj1M
Session Token:   7Y6SaanfrLmiOXoE2kUvTbdEfawIMSJyGDaNFPf1-Bg
Authenticated:   true
User ID:         user_1b25e4982c9904b8
========================================

Step 4: Test Invalid Token
GET /auth/status -H 'Authorization: Bearer invalid_token_123'
Response: {"authenticated":false,"user_id":null}

SUCCESS: Complete auth flow working correctly!

You can now use this token for MCP:
Authorization: Bearer 7Y6SaanfrLmiOXoE2kUvTbdEfawIMSJyGDaNFPf1-Bg

Bereitstellung

Für die Produktion passen Sie Folgendes an:

1. FLASK_SECRET_KEY - Verwenden Sie einen starken, zufälligen Schlüssel

2. OAuth-Anbieter - Ersetzen Sie ihn durch einen echten OAuth-Anbieter (Google, GitHub usw.)

3. Token-Speicherung - Verwenden Sie eine Datenbank anstelle von .auth_tokens.json

4. HTTPS - Aktivieren Sie SSL/TLS für die Authentifizierungs-Endpunkte

Hinweise zur Architektur

Dieses Beispiel veranschaulicht:

• Trennung der Verantwortlichkeiten: API-Client, Geschäftslogik und MCP-Ebene sind unabhängig voneinander

• Schichtenarchitektur: Einfach zu testen und Komponenten austauschbar

• Authentifizierungs-Integration: Auth-Tokens werden über Parameter übergeben, nicht über Header

• Fehlerbehandlung: Ordnungsgemäße Fehlerantworten bei Authentifizierungsfehlern

Der API-Client verwendet https://jsonplaceholder.typicode.com als Demo-API. Ersetzen Sie ihn durch Ihre eigene API-Implementierung, ohne die MCP-/Geschäftsschnittstellen zu ändern.