Herramientas MCP con autenticación OAuth

Un ejemplo en Python que demuestra cómo construir un servidor MCP (Model Context Protocol) con autenticación OAuth, combinando un cliente de API, una capa de lógica de negocio y herramientas MCP protegidas.

Características

• Flujo de autenticación OAuth: autenticación con un clic en el navegador para tokens de sesión

• Arquitectura en capas: Cliente de API → Lógica de negocio → Herramientas MCP

• Acceso seguro a las herramientas: Requiere un token de autenticación válido para llamar a las herramientas protegidas

• Servidor HTTP simple: servidor de autenticación basado en que se opone** "Serventa en localhost:5000

• Gestión de se token tokens: tokens de sesión de 24 horas con persistencia

Related MCP server: OAuth MCP Server

Arquitectura

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

Instalación

python -m venv .venv

# Windows:
.venv\Scripts\activate

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

pip install -r requirements.txt

Inicio rápido

1. Inicia el servidor de autenticación

python -m src.example.http.auth_server

Esto inicia un servidor Flask en http://localhost:5000 con un flujo de autenticación OAuth:

• Visita la página de inicio

• Hace cl ic en "Click to Authenticate"

• Obén tu token de sesión en la página de llamca

• Copia y guarda tu token

2. Inicia el servidor MCP

En otro terminal:

python -m src.example.mcp.server

3. Usa las herramientos MCP

El servidor MCP ahora requieren la autenticación. Peña, obén la URL de autenticación:

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

Luego autentícate y usa las herramientos con tu 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

Flujo de autenticación

1. Obén la URL de autenticación: Llaa a la herramiento get_auth_url (no es necesaria la autenticación)

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

2. Clic en el navegador: El usuario hce cl ic en la URL de autenticación devuelta

   • • E se el http://localhost:5000/auth/callback?state=...

   • El navegador mustra una página de éxito con el token de sesión

   • El token es válido durante 24 horas

3. Usa the token: Include auth_token en todas las llamadas a la herramientas

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

Herramientas as disponibles

Públicas (sin autenticación)

• get_auth_url - Obén la URL de autenticator OAuth

Protegidas (autenticator requerida)

• get_user - Obén un usuario por ID

• list_users - Listar todos los usuarios

• create_user - Crear un nuevo usuario

• update_user - Actualizar el nombre/correo electrónico del de usuario

• delete_user - Elimina a un usuario

Configuración

Establee las variables de entorno:

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

Pruebas

Ejecuta las pruebas con pytest:

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

Ejecuta el script de shell

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

Despliegue

Para producción, actualiza:

1. FLASK_SECRET_KEY - Usa una clave aleatoria fuerte

2. Proveedor de OAuth - Reemplaza por un proveedor de code** OAuth real (Google, GitHub, etc.)

3. Almacenamiento de tokens - Usa una base de datos en lugar de .auth_tokens.json

4. HTTPS - Habilita SSL/TLS para los endpoints de autenticación

Notas de arquitectura

Este ejemplo demuestra:

• Separación de responsabilidades: El cliente de API, la lógica de negocio y la capa MCP son independientes

• Diseño en capas: Fácil de probar y reemplazar componentes

• Integración de autenticación: Los tokens de autenticación se pasan a través de los parámetros, no de los encabezados

• Manejo de errores: Respuestas de error apropiadas para fallos de autenticación

El cliente de lahttps://jsonplaceholder.typicode.com como API de demostración. Replaza por tu propia implementación de API sin cambiar las interfaces MCP/negocio.