Ir al contenido principal
Español— Elegir un idioma
Menú

OAuth 2.0 para servidores MCP

Lección 8 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. ¿Por qué OAuth en MCP?
  2. Cómo funciona el flujo
  3. Configuración de OAuth en el cliente de Python
  4. Mínimo privilegio, aplicado a los ámbitos
  5. Almacenamiento y renovación de tokens
  6. Cuándo basta un token simple
  7. Qué gestiona Vibe por ti
  8. Puntos clave

Actualización 2 de noviembre de 2026 — Le Chat pasa a llamarse Vibe. Desde el 28 de mayo de 2026, Le Chat ha cambiado de marca y ahora se llama Vibe (sigue estando en chat.mistral.ai): un único agente para trabajo y código que conserva tus conversaciones, configuraciones y suscripciones. La experiencia heredada de Le Chat sigue accesible en el modo Chat; en el modo Work, los agentes se han convertido en habilidades (que se invocan con @), las memorias son ahora la base de conocimientos y la búsqueda profunda es la habilidad Deep Research. Los planes se llaman ahora Mistral Free, Pro, Team y Enterprise. Esta lección utiliza el nombre Vibe; es posible que algunos menús descritos aquí hayan cambiado de nombre o ubicación. Addendum 3 de noviembre: el ejemplo anterior llamaba a requires_auth, set_oauth_params o get_token_from_auth_response en MCPClientStreamableHTTP, que no tiene ninguno de estos métodos en la versión 3.7.0 del SDK mistralai; ahora sigue el ejemplo oficial async_conversation_run_mcp_remote_auth.py, que usa MCPClientSSE. Fuente: client-python, ejemplos de MCP.

¿Por qué OAuth en MCP?

Mientras tu servidor MCP solo convierta divisas o consulte una base de datos pública, la identidad no es un problema. Se vuelve crítica en el momento en que el servidor toca correos electrónicos, calendarios, repositorios de GitHub o tickets de Linear: ya no trabaja por sí mismo, actúa en nombre de un usuario concreto. Un token estático guardado en un fichero de configuración no dice nada sobre este consentimiento. No indica quién autorizó qué, durante cuánto tiempo ni hasta dónde se extienden los derechos concedidos. OAuth 2.0 cubre exactamente estas tres lagunas: consentimiento explícito, derechos limitados por ámbitos (scopes) y renovación segura.

Recuerda los tres niveles de autenticación vistos anteriormente. El primero, sin autenticación, sirve para una URL pública sin datos sensibles. El segundo, token estático, corresponde a una clave de API generada manualmente, como un Token de Acceso Personal de GitHub. El tercero, OAuth 2.0, añade todo el flujo de consentimiento con ámbitos y tokens de actualización. Pasar del segundo al tercer nivel no es cuestión de sofisticación técnica, sino de responsabilidad: en cuanto varias personas usan tu servidor sobre sus propios datos, un token compartido se convierte en un agujero de seguridad.

Cómo funciona el flujo

Cuando un usuario conecta un servidor MCP con OAuth en Vibe, se encadenan siete pasos. Merece la pena visualizarlos de una vez por todas:

1. El usuario hace clic en "Connect" en Vibe
       ↓
2. Vibe redirige a la página de autorización del servicio
   (p. ej., GitHub, Google, Linear)
       ↓
3. El usuario concede los permisos solicitados (ámbitos)
       ↓
4. El servicio devuelve un código de autorización al callback
       ↓
5. El cliente canjea el código por un token de acceso + token de actualización
       ↓
6. El token de acceso se usa en cada llamada MCP
       ↓
7. Cuando caduca el token de acceso, el token de actualización obtiene uno nuevo

En esta coreografía circulan tres tokens distintos, que a menudo se confunden. El código de autorización es temporal y de un solo uso: se canjea inmediatamente por los tokens reales. El token de acceso acompaña entonces a cada petición y tiene una vida breve, normalmente una hora. El token de actualización, por último, sirve solo para obtener un nuevo token de acceso sin pedir de nuevo el consentimiento al usuario. Esta corta vida del token de acceso es una salvaguarda: si se filtra un token, su ventana de explotación permanece estrecha.

Configuración de OAuth en el cliente de Python

El SDK de Mistral admite este flujo con la función auxiliar build_oauth_params y algunos métodos del cliente MCP. Vigila qué cliente eliges: en la versión 3.7.0 del SDK mistralai, estos métodos OAuth solo existen en el cliente SSE, MCPClientSSE, que es el que usa el ejemplo oficial del SDK con el servidor de Linear; MCPClientStreamableHTTP no tiene ninguno de ellos.

from mistralai.extra.mcp.auth import build_oauth_params
from mistralai.extra.mcp.sse import MCPClientSSE, SSEServerParams

REDIRECT_URL = "http://localhost:16010/oauth/callback"
SERVER_URL = "https://mcp.linear.app/sse"

mcp_client = MCPClientSSE(sse_params=SSEServerParams(url=SERVER_URL))

async def connect():
    global mcp_client
    if not await mcp_client.requires_auth():
        return mcp_client  # El servidor está abierto: nada que hacer

    # 1. Descubrir los endpoints OAuth del servidor
    #    (y registrar dinámicamente el cliente si no se proporciona client_id)
    oauth_params = await build_oauth_params(
        mcp_client.base_url,
        redirect_url=REDIRECT_URL,
    )
    mcp_client.set_oauth_params(oauth_params=oauth_params)

    # 2. Construir la URL de consentimiento y abrirla en el navegador
    login_url, state = await mcp_client.get_auth_url_and_state(REDIRECT_URL)
    print(f"Autorizar acceso: {login_url}")

    # 3. Capturar el callback y canjear el código por un token,
    #    usando un cliente recreado a partir de los parámetros OAuth guardados
    auth_response = await wait_for_callback()  # pequeño servidor HTTP local
    mcp_client = MCPClientSSE(sse_params=SSEServerParams(url=SERVER_URL), oauth_params=oauth_params)
    token = await mcp_client.get_token_from_auth_response(
        auth_response["url"],
        redirect_url=REDIRECT_URL,
        state=state,
    )
    mcp_client.set_auth_token(token)
    return mcp_client

build_oauth_params hace dos cosas y solo dos: lee los metadatos OAuth publicados por el servidor MCP y registra dinámicamente un cliente si no pasas ni client_id ni client_secret. El resto del flujo corre de tu cuenta: abrir la URL de consentimiento, recoger el callback en el puerto de tu redirect_url y canjear el código por un token. El SDK no oculta estos pasos; los instrumentaliza, y precisamente este desglose te permite conectar el callback en una aplicación web en lugar de en un script.

Mínimo privilegio, aplicado a los ámbitos

Los ámbitos definen qué puede hacer tu servidor una vez concedido el consentimiento, y la pantalla de consentimiento se los muestra al usuario. Es tentador pedir de forma amplia: así evitas tener que volver atrás si surge una necesidad. También es la mejor manera de asustar a un usuario prudente y exponer innecesariamente su cuenta. Compara:

# Malo: demasiados permisos
scope=["repo", "admin:org", "delete_repo", "user"]

# Bueno: lo justo para crear incidencias
scope=["repo:issues", "read:user"]

Un servidor que crea incidencias no tiene motivo para borrar repositorios ni administrar la organización. Cada servicio publica su propia nomenclatura de ámbitos: consulta la documentación OAuth del servicio objetivo en lugar de adivinar por analogía.

Almacenamiento y renovación de tokens

Los tokens que obtienes valen lo mismo que las credenciales a las que sustituyen y merecen el mismo cuidado. Escríbelos en un fichero dedicado con permisos de sistema restringidos:

import os
import json
from pathlib import Path

TOKEN_FILE = Path.home() / ".mcp" / "tokens.json"

def save_tokens(service: str, access_token: str, refresh_token: str):
    """Guardar tokens de forma segura."""
    TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
    tokens = {}
    if TOKEN_FILE.exists():
        tokens = json.loads(TOKEN_FILE.read_text())
    tokens[service] = {
        "access_token": access_token,
        "refresh_token": refresh_token,
    }
    TOKEN_FILE.write_text(json.dumps(tokens))
    # Restringir permisos del fichero
    os.chmod(TOKEN_FILE, 0o600)

El chmod a 0o600 no es decorativo: sin él, en una máquina compartida, cualquier cuenta puede leer tus tokens. La renovación, por su parte, se reduce a una llamada POST a la token_url del servicio con el token de actualización en la mano. El usuario no ve pasar nada, que es justamente la idea:

import httpx

async def refresh_access_token(
    token_url: str,
    client_id: str,
    client_secret: str,
    refresh_token: str,
) -> dict:
    """Renovar el token de acceso mediante el token de actualización."""
    async with httpx.AsyncClient() as http:
        response = await http.post(
            token_url,
            data={
                "grant_type": "refresh_token",
                "refresh_token": refresh_token,
                "client_id": client_id,
                "client_secret": client_secret,
            },
        )
        response.raise_for_status()
        return response.json()

Cuándo basta un token simple

No todo servidor justifica esta maquinaria. Para una herramienta interna que consumen un puñado de desarrolladores, una clave de API pasada en una cabecera HTTP funciona perfectamente, y el cliente MCP la acepta directamente:

from mistralai.extra.mcp.streamable_http import (
    MCPClientStreamableHTTP,
    StreamableHTTPServerParams,
)

# Servidor con token simple
mcp_client = MCPClientStreamableHTTP(
    params=StreamableHTTPServerParams(
        url="https://my-server.com/mcp",
        headers={"Authorization": "Bearer my_secret_api_token"},
        timeout=60,
    )
)

En el lado del servidor, la verificación encaja en un middleware que intercepta las rutas relevantes antes de que lleguen a tu lógica de negocio:

from fastapi import FastAPI, Request, HTTPException

api = FastAPI()

@api.middleware("http")
async def verify_token(request: Request, call_next):
    if request.url.path.startswith("/mcp"):
        token = request.headers.get("Authorization", "")
        if token != "Bearer my_secret_api_token":
            raise HTTPException(status_code=401, detail="Unauthorized")
    return await call_next(request)

Qué gestiona Vibe por ti

En Vibe, los conectores destacados —GitHub, Gmail, Linear— vienen con OAuth ya configurado: el usuario hace clic, consiente y listo. Para tus conectores personalizados, la configuración ofrece las mismas tres opciones descritas antes: Sin autenticación para una URL pública, Token si pegas la clave a mano y OAuth 2.0 para el flujo completo. Un detalle tiene consecuencias prácticas importantes: el token se almacena por usuario, no por organización. En un equipo de Mistral, cada miembro pasa por su propio consentimiento y trabaja con sus propias credenciales, lo que evita que una baja o una revocación rompa el acceso para todos.

Puntos clave

  • OAuth 2.0 permite un consentimiento explícito con derechos limitados (ámbitos)
  • El flujo: autorización → código → tokens (acceso + actualización)
  • Aplica el principio de mínimo privilegio a los ámbitos
  • Los tokens deben almacenarse de forma segura y renovarse automáticamente
  • Para casos simples, basta un token estático en cabeceras HTTP
  • En Vibe, los tokens se almacenan por usuario