OAuth 2.0 pentru serverele MCP
Pe această pagină
Actualizare 2 noiembrie 2026 — Le Chat devine Vibe. Începând cu 28 mai 2026, Le Chat a fost rebotezat Vibe (rămânând la chat.mistral.ai): un singur agent pentru muncă și cod, care preia conversațiile, setările și abonamentele dumneavoastră. Experiența legacy Le Chat rămâne accesibilă în modul Chat; în modul Work, agenții au devenit competențe (invocate cu
@'), memoriile sunt acum baza de cunoștințe, iar căutarea avansată este competența Deep Research. Planurile se numesc acum Mistral Free, Pro, Team și Enterprise. Această lecție folosește denumirea Vibe; unele meniuri descrise aici își pot fi schimbat numele sau locația. *Addendum 3 noiembrie: Exemplul anterior apelarequires_auth,set_oauth_paramssauget_token_from_auth_responsepeMCPClientStreamableHTTP, care nu posedă niciuna dintre aceste metode în SDK-ulmistralai3.7.0; acum urmează exemplul oficialasync_conversation_run_mcp_remote_auth.py, folosindMCPClientSSE`. Sursă: client-python, exemple MCP.*
De ce OAuth în MCP?
Atâta timp cât serverul dumneavoastră MCP doar convertește valute sau interoghează o bază de date publică, identitatea nu reprezintă o problemă. Aceasta devine critică în momentul în care serverul atinge e-mailuri, calendare, depozite GitHub sau tichete Linear: el nu mai lucrează pentru sine, ci acționează în numele unui utilizator specific. Un token static aflat într-un fișier de configurare nu spune nimic despre acest consimțământ. Nu indică cine a autorizat ce, pentru cât timp, nici cât de departe se extind drepturile acordate. OAuth 2.0 rezolvă exact aceste trei lacune: consimțământ explicit, drepturi limitate prin scope-uri și reînnoire securizată.
Reamintiți-vă cele trei niveluri de autentificare abordate anterior. Primul, fără autentificare, se potrivește unui URL public fără date sensibile. Al doilea, token static, corespunde unei chei API generate manual, precum un GitHub Personal Access Token. Al treilea, OAuth 2.0, adaugă fluxul complet de consimțământ cu scope-uri și token-uri de reîmprospătare. Trecerea de la al doilea la al treilea nivel nu ține de sofisticare tehnică, ci de responsabilitate: odată ce mai multe persoane utilizează serverul dumneavoastră pe propriile lor date, un token partajat devine o breșă de securitate.
Cum funcționează fluxul
Când un utilizator conectează un server MCP cu OAuth în Vibe, șapte pași se înlănțuie. Merită să îi vizualizați o dată pentru totdeauna:
1. Utilizatorul face clic pe „Conectare“ în Vibe
↓
2. Vibe redirecționează către pagina de autorizare a serviciului
(de ex. GitHub, Google, Linear)
↓
3. Utilizatorul acordă permisiunile solicitate (scope-uri)
↓
4. Serviciul returnează un cod de autorizare către callback
↓
5. Clientul schimbă codul pe un token de acces + token de reîmprospătare
↓
6. Token-ul de acces este folosit pentru fiecare apel MCP
↓
7. Când token-ul de acces expiră, token-ul de reîmprospătare obține unul nou
Trei token-uri diferite circulă în această coregrafie și sunt adesea confundate. Codul de autorizare este temporar și de unică folosință: este schimbat imediat pe token-urile reale. Token-ul de acces însoțește apoi fiecare cerere și are o durată de viață scurtă, tipic o oră. Token-ul de reîmprospătare, în final, servește doar pentru a obține un nou token de acces fără a cere din nou consimțământul utilizatorului. Această durată scurtă de viață a token-ului de acces este o măsură de siguranță: dacă un token scapă, fereastra sa de exploatare rămâne îngustă.
Configurarea OAuth pe clientul Python
SDK-ul Mistral suportă acest flux cu funcția auxiliară build_oauth_params și câteva metode ale clientului MCP. Fiți atent la alegerea clientului: în SDK-ul mistralai 3.7.0, aceste metode OAuth există doar pe clientul SSE, MCPClientSSE, pe care exemplul oficial al SDK-ului îl folosește cu serverul Linear; MCPClientStreamableHTTP nu posedă niciuna dintre ele.
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 # Serverul este deschis: nimic de făcut
# 1. Descoperirea endpoint-urilor OAuth ale serverului
# (și înregistrarea dinamică a clientului dacă nu se furnizează 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. Construirea URL-ului de consimțământ și deschiderea lui în browser
login_url, state = await mcp_client.get_auth_url_and_state(REDIRECT_URL)
print(f"Autorizați accesul: {login_url}")
# 3. Captarea callback-ului, apoi schimbul codului pe un token,
# folosind un client recreat din parametrii OAuth salvați
auth_response = await wait_for_callback() # mic server 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 face două lucruri și doar două: citește metadatele OAuth publicate de serverul MCP și înregistrează dinamic un client dacă nu transmiteți nici client_id, nici client_secret. Restul fluxului vă revine dumneavoastră—deschiderea URL-ului de consimțământ, colectarea callback-ului pe portul dumneavoastră redirect_url, schimbul codului pe un token. SDK-ul nu ascunde acești pași; îi instrumentează, iar tocmai această descompunere vă permite să conectați callback-ul într-o aplicație web plutôt decât într-un script.
Privilegiul minim, aplicat scope-urilor
Scope-urile definesc ce poate face serverul dumneavoastră odată acordat consimțământul, iar ecranul de consimțământ le afișează utilizatorului. Este tentant să cereți larg: evită revenirea în spate dacă apare o nevoie. Este însă și cea mai bună metodă de a speria un utilizator prudent și de a expune inutil contul acestuia. Comparați:
# Rău: prea multe permisiuni
scope=["repo", "admin:org", "delete_repo", "user"]
# Bun: strictul necesar pentru a crea issue-uri
scope=["repo:issues", "read:user"]
Un server care creează issue-uri nu are niciun motiv să șteargă depozite sau să administreze organizația. Fiecare serviciu publică propria sa nomenclatură de scope-uri: consultați documentația OAuth a serviciului țintă în loc să ghiciți prin analogie.
Stocarea și reînnoirea token-urilor
Token-urile pe care le obțineți valorează cât credențialele pe care le înlocuiesc și merită aceeași grijă. Scrieți-le într-un fișier dedicat cu permisiuni de sistem restricționate:
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):
"""Salvează token-urile în siguranță."""
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))
# Restricționarea permisiunilor fișierului
os.chmod(TOKEN_FILE, 0o600)
Comanda chmod la 0o600 nu este decorativă: fără ea, pe o mașină partajată, orice cont vă poate citi token-urile. Reînnoirea, între timp, se reduce la un apel POST către token_url al serviciului, având în mână token-ul de reîmprospătare. Utilizatorul nu vede nimic trecând, ceea ce este chiar scopul:
import httpx
async def refresh_access_token(
token_url: str,
client_id: str,
client_secret: str,
refresh_token: str,
) -> dict:
"""Reînnoiește token-ul de acces prin token-ul de reîmprospătare."""
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()
Când un token simplu este suficient
Nu fiecare server justifică acest mecanism. Pentru un instrument intern consumat de câțiva dezvoltatori, o cheie API transmisă într-un antet HTTP funcționează perfect, iar clientul MCP o acceptă direct:
from mistralai.extra.mcp.streamable_http import (
MCPClientStreamableHTTP,
StreamableHTTPServerParams,
)
# Server cu token simplu
mcp_client = MCPClientStreamableHTTP(
params=StreamableHTTPServerParams(
url="https://my-server.com/mcp",
headers={"Authorization": "Bearer my_secret_api_token"},
timeout=60,
)
)
Pe partea de server, verificarea se încadrează într-un middleware care interceptează rutele relevante înainte ca acestea să ajungă la logica de afaceri:
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)
Ce gestionează Vibe pentru dumneavoastră
În Vibe, conectorii evidențiați—GitHub, Gmail, Linear—vin cu OAuth deja configurat: utilizatorul face clic, consimte și gata. Pentru conectorii dumneavoastră personalizați, configurația oferă aceleași trei opțiuni descrise mai sus: Fără autentificare pentru un URL public, Token dacă lipiți cheia manual, și OAuth 2.0 pentru fluxul complet. Un detaliu are consecințe practice importante: token-ul este stocat per utilizator, nu per organizație. Într-o echipă Mistral, fiecare membru trece therefore prin propriul consimțământ și lucrează cu propriile credențiale—ceea ce previne ca o plecare sau o revocare să blocheze accesul pentru toată lumea.
Puncte cheie
- OAuth 2.0 permite consimțământul explicit cu drepturi limitate (scope-uri)
- Fluxul: autorizare → cod → token-uri (acces + reîmprospătare)
- Aplicați principiul privilegiului minim scope-urilor
- Token-urile trebuie stocate securizat și reînnoite automat
- Pentru cazuri simple, un token static în anteturile HTTP este suficient
- În Vibe, token-urile sunt stocate per utilizator