Cómo crear un servidor MCP remoto con OAuth en Python: un ejemplo real

Un servidor MCP local en el portátil de un desarrollador es fácil. Un servidor MCP remoto que usa todo un equipo desde Claude, ChatGPT o Cursor, en el que cada persona inicia sesión con su propia cuenta y la IA solo puede hacer lo que esa persona tiene permitido, requiere algo más de diseño. Esta guía recorre la arquitectura que usamos para nuestro propio servidor en octubre de 2026: un servidor MCP en Python que conecta Claude con nuestro gestor de tareas interno.

¿Es nuevo en MCP? Empiece por qué es un servidor MCP.

La arquitectura

1. Su aplicación (aquí, una aplicación Django) es el servidor de autorización OAuth: las personas inician sesión con las cuentas que ya tienen y aprueban el acceso.
2. El servidor MCP es el servidor de recursos: recibe el token de acceso del usuario desde la aplicación de IA, lo verifica con el servidor de autorización y solo entonces ejecuta la herramienta.
3. La aplicación de IA (Claude, ChatGPT, Cursor, Claude Code) descubre cómo iniciar sesión a partir de los metadatos del servidor MCP, guía al usuario por el inicio de sesión y llama a las herramientas con el token.

Hay una decisión de diseño muy importante: el servidor MCP nunca reenvía el token del usuario a la API interna de la aplicación. Llama a la aplicación con sus propias credenciales de servicio e indica en nombre de qué usuario actúa, y la aplicación aplica los permisos de ese usuario. Así, un token de IA filtrado no puede reutilizarse contra el resto de su sistema.

Paso 1: diseñe las herramientas antes de escribir código

Las herramientas son lo que ve la IA, así que diséñelas como un producto:

• Pocas y específicas: nuestro servidor tiene 11 herramientas, como search_tasks, summarize_tasks, create_tasks y add_comment.
• Marque las herramientas de solo lectura como de solo lectura, para que las aplicaciones de IA puedan tratarlas de forma distinta a las que modifican datos.
• Devuelva resultados compactos (ID, títulos, estado, enlaces), no filas completas de la base de datos.
• Permita que las herramientas de escritura trabajen por lotes con límites (nosotros permitimos de 1 a 50 tareas por llamada) para que la IA no repita la llamada cientos de veces.
• Escriba descripciones claras: la IA elige las herramientas leyéndolas.

Paso 2: el servidor MCP en Python

Usamos el SDK oficial de Python (el paquete mcp) con el transporte Streamable HTTP, servido en /mcp. Una versión simplificada de la configuración es esta:

from mcp.server.mcpserver import MCPServer
from mcp.server.auth.settings import AuthSettings
from mcp.types import ToolAnnotations

READ_ONLY = ToolAnnotations(read_only_hint=True, open_world_hint=False)

mcp = MCPServer(
    name="tasks",
    token_verifier=IntrospectionVerifier(),   # checks tokens with your OAuth server
    auth=AuthSettings(
        issuer_url="https://app.example.com",
        resource_server_url="https://mcp.example.com/mcp",
        required_scopes=["tasks:read"],
    ),
)

@mcp.tool(annotations=READ_ONLY)
async def search_tasks(query: str, overdue: bool = False) -> list[dict]:
    """Search tasks the signed-in person can see."""
    user = current_user()                      # from the verified token
    return await app_api.search(user, query=query, overdue=overdue)

Consulte la documentación actual del SDK para conocer los nombres exactos, porque los SDK evolucionan rápidamente.

Paso 3: inicio de sesión OAuth y scopes

• Servidor de autorización: nuestra aplicación usa django-oauth-toolkit para emitir tokens y responder a las solicitudes de introspección de tokens. Cualquier servidor OAuth 2 de su confianza puede hacer este trabajo.
• Descubrimiento: el servidor MCP publica metadatos de recurso protegido. Cuando una aplicación de IA llama a /mcp sin token, recibe una respuesta 401 que apunta a esos metadatos y, desde ahí, a su página de inicio de sesión.
• Scopes: usamos tasks:read para todo lo que solo lee y tasks:write para cualquier cosa que modifique datos. Una persona puede conectarse con acceso de solo lectura.
• Verificación de tokens: el servidor MCP verifica cada token con el servidor de autorización, incluido para quién se emitió, antes de que se ejecute cualquier herramienta.

Paso 4: despliéguelo

• Empaquete el servidor en un pequeño contenedor Docker con un endpoint de comprobación de estado (health check).
• Póngalo detrás de HTTPS (nginx, Caddy o un balanceador de carga en la nube) y desactive el buffering de respuestas en la ruta MCP, o las respuestas en streaming se quedarán bloqueadas.
• La URL pública que anuncia el servidor debe coincidir exactamente con la URL que las personas introducen en su aplicación de IA.
• Asegúrese de que los firewalls, las CDN o la protección contra bots no impidan que los servidores del proveedor de IA lleguen a sus endpoints de inicio de sesión y de metadatos; es el motivo más habitual por el que falla un botón "Connect".

Paso 5: pruebe antes de conectar usuarios reales

Probamos el servidor MCP de extremo a extremo contra una versión simulada en memoria de la aplicación, y el lado de la aplicación tiene sus propias pruebas de OAuth, permisos y la API interna. Antes del lanzamiento, compruebe a mano que: una llamada sin token devuelve 401 con el enlace a los metadatos, un token de solo lectura se rechaza en las herramientas de escritura y un usuario no puede ver los datos privados de otro usuario.

Paso 6: conéctelo en Claude, ChatGPT o Cursor

• Claude (equipo): un propietario añade un conector personalizado con la URL del servidor MCP; cada persona hace clic en Connect e inicia sesión.
• Claude Code: claude mcp add --transport http tasks https://mcp.example.com/mcp y, después, inicie sesión.
• Otras aplicaciones: la mayoría de las aplicaciones compatibles con MCP tienen un lugar para añadir la URL de un servidor MCP remoto; consulte su documentación.

Errores comunes

• Dar a la IA una única herramienta potente para "ejecutar cualquier consulta" en lugar de unas pocas herramientas seguras y específicas.
• Usar una sola clave de API compartida para todos, de modo que no se puede saber quién hizo qué.
• Reenviar los tokens de usuario directamente a los sistemas internos.
• No tener registros: siempre debería poder responder a "¿quién pidió a la IA que cambiara esto, y cuándo?"

Cómo puede ayudarle UnlockLive

Creamos y operamos servidores MCP remotos para CRM, bases de datos, ERP y API internas, con inicio de sesión por usuario, scopes, registros y pruebas. Consulte nuestro servicio de desarrollo de servidores MCP, la lista de comprobación de seguridad MCP y el caso práctico de nuestro propio servidor. Díganos qué sistema quiere conectar.