OAuth 2.0 dla serwerów MCP
Na tej stronie
Aktualizacja z 2 listopada 2026 r. — Le Chat to teraz Vibe. Od 28 maja 2026 r. Le Chat zmienił nazwę na Vibe (nadal pod adresem chat.mistral.ai): to pojedynczy agent do pracy i kodowania, który zachowuje Twoje konwersacje, ustawienia i subskrypcje. Starsza wersja Le Chat jest nadal dostępna w trybie Chat; w trybie Work agenci stali się umiejętnościami (wywoływanymi za pomocą
@), pamięć to teraz baza wiedzy, a głębokie wyszukiwanie to umiejętność Deep Research. Plany noszą teraz nazwy Mistral Free, Pro, Team i Enterprise. W tej lekcji używamy nazwy Vibe; niektóre opisane tu menu mogły zmienić nazwy lub lokalizację. Dodatkowa uwaga z 3 listopada: poprzedni przykład wywoływał metodyrequires_auth,set_oauth_paramslubget_token_from_auth_responsena obiekcieMCPClientStreamableHTTP, który nie posiada żadnej z tych metod w SDKmistralaiw wersji 3.7.0; obecnie przykład podąża za oficjalnym wzorcemasync_conversation_run_mcp_remote_auth.py, używającMCPClientSSE. Źródło: client-python, przykłady MCP.
Dlaczego OAuth w MCP?
Dopóki Twój serwer MCP jedynie przelicza waluty lub odpytuje publiczną bazę danych, kwestia tożsamości nie stanowi problemu. Staje się ona kluczowa w momencie, gdy serwer zaczyna dotykać e-maili, kalendarzy, repozytoriów GitHub czy zgłoszeń w Linear: nie działa już sam dla siebie, lecz działa w imieniu konkretnego użytkownika. Statyczny token leżący w pliku konfiguracyjnym nic nie mówi o tej zgodzie. Nie wskazuje, kto, na jak długo i w jakim zakresie autoryzował dostęp. OAuth 2.0 wypełnia dokładnie te trzy luki: wyraźna zgoda, prawa ograniczone zakresami (scopes) oraz bezpieczne odnawianie dostępu.
Przypomnijmy trzy omówione wcześniej poziomy uwierzytelniania. Pierwszy, brak uwierzytelniania, pasuje do publicznego URL-a bez danych wrażliwych. Drugi, statyczny token, odpowiada kluczowi API wygenerowanemu ręcznie, np. GitHub Personal Access Token. Trzeci, OAuth 2.0, dodaje pełny proces zgody z zakresami i tokenami odnawiającymi. Przejście z drugiego na trzeci poziom nie wynika z technicznego wyrafinowania, lecz z odpowiedzialności: gdy z Twojego serwera korzysta wiele osób na swoich danych, współdzielony token staje się dziurą bezpieczeństwa.
Jak działa przepływ
Gdy użytkownik łączy serwer MCP z OAuth w Vibe, następuje siedem następujących po sobie kroków. Warto je raz na zawsze zwizualizować:
1. Użytkownik klika "Połącz" w Vibe
↓
2. Vibe przekierowuje do strony autoryzacji usługi
(np. GitHub, Google, Linear)
↓
3. Użytkownik przyznaje żądane uprawnienia (scopes)
↓
4. Usługa zwraca kod autoryzacyjny do callbacka
↓
5. Klient wymienia kod na token dostępu + token odnawiający
↓
6. Token dostępu jest używany przy każdym wywołaniu MCP
↓
7. Gdy token dostępu wygasa, token odnawiający pozwala uzyskać nowy
W tej choreografii krążą trzy różne tokeny, które często są mylone. Kod autoryzacyjny jest tymczasowy i jednorazowy: natychmiast wymienia się go na właściwe tokeny. Token dostępu towarzyszy następnie każdemu żądaniu i żyje krótko, zazwyczaj godzinę. Token odnawiający służy wyłącznie do uzyskania nowego tokena dostępu bez ponownego proszenia użytkownika o zgodę. Krótki czas życia tokena dostępu jest zabezpieczeniem: jeśli token wycieknie, okno jego eksploatacji pozostaje wąskie.
Konfiguracja OAuth w kliencie Pythona
SDK Mistral obsługuje ten przepływ za pomocą funkcji pomocniczej build_oauth_params i kilku metod klienta MCP. Zwróć uwagę na wybór klienta: w SDK mistralai w wersji 3.7.0 metody OAuth istnieją wyłącznie w kliencie SSE, MCPClientSSE, którego oficjalny przykład SDK używa z serwerem Linear; MCPClientStreamableHTTP nie posiada żadnej z nich.
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 # Serwer jest otwarty: nic do zrobienia
# 1. Odkryj punkty końcowe OAuth serwera
# (i dynamicznie zarejestruj klienta, jeśli nie podano 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. Zbuduj URL zgody i otwórz go w przeglądarce
login_url, state = await mcp_client.get_auth_url_and_state(REDIRECT_URL)
print(f"Autoryzuj dostęp: {login_url}")
# 3. Przechwyć callback, a następnie wymień kod na token,
# używając klienta utworzonego ponownie na podstawie zapisanych parametrów OAuth
auth_response = await wait_for_callback() # mały lokalny serwer HTTP
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 robi dwie i tylko dwie rzeczy: odczytuje metadane OAuth publikowane przez serwer MCP i dynamicznie rejestruje klienta, jeśli nie przekażesz ani client_id, ani client_secret. Reszta przepływu zależy od Ciebie — otwarcie URL-a zgody, zebranie callbacka na porcie Twojego redirect_url, wymiana kodu na token. SDK nie ukrywa tych kroków; dostarcza narzędzi do ich realizacji, a właśnie ta dekompozycja pozwala podpiąć callback pod aplikację webową, a nie tylko skrypt.
Minimalne uprawnienia zastosowane do zakresów (scopes)
Zakresy definiują, co Twój serwer może zrobić po uzyskaniu zgody, a ekran zgody wyświetla je użytkownikowi. Kusi, by prosić o wszystko: unikniesz wtedy cofania się, jeśli pojawi się nowa potrzeba. To jednak najlepszy sposób, by przestraszyć ostrożnego użytkownika i niepotrzebnie narazić jego konto na ryzyko. Porównaj:
# Źle: zbyt wiele uprawnień
scope=["repo", "admin:org", "delete_repo", "user"]
# Dobrze: tylko tyle, by tworzyć zgłoszenia
scope=["repo:issues", "read:user"]
Serwer tworzący zgłoszenia nie ma powodu, by usuwać repozytoria lub administrować organizacją. Każda usługa publikuje własną nomenklaturę zakresów: consultuj dokumentację OAuth docelowej usługi, zamiast zgadywać przez analogię.
Przechowywanie i odnawianie tokenów
Tokeny, które uzyskasz, są warte tyle, co poświadczenia, które zastępują, i zasługują na taką samą opiekę. Zapisz je w dedykowanym pliku z ograniczonymi uprawnieniami systemowymi:
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):
"""Bezpiecznie zapisz tokeny."""
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))
# Ogranicz uprawnienia do pliku
os.chmod(TOKEN_FILE, 0o600)
Zmiana uprawnień chmod na 0o600 nie jest ozdobnikiem: bez niej na współdzielonej maszynie każde konto może odczytać Twoje tokeny. Odnowienie sprowadza się natomiast do wywołania POST na token_url usługi z posiadaniem tokena odnawiającego. Użytkownik niczego nie widzi, i właśnie o to chodzi:
import httpx
async def refresh_access_token(
token_url: str,
client_id: str,
client_secret: str,
refresh_token: str,
) -> dict:
"""Odnow token dostępu za pomocą tokena odnawiającego."""
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()
Kiedy prosty token wystarczy
Nie każdy serwer usprawiedliwia tę machinerię. W przypadku narzędzia wewnętrznego używanego przez garstkę programistów, klucz API przekazany w nagłówku HTTP działa równie dobrze, a klient MCP przyjmuje go bezpośrednio:
from mistralai.extra.mcp.streamable_http import (
MCPClientStreamableHTTP,
StreamableHTTPServerParams,
)
# Serwer z prostym tokenem
mcp_client = MCPClientStreamableHTTP(
params=StreamableHTTPServerParams(
url="https://my-server.com/mcp",
headers={"Authorization": "Bearer my_secret_api_token"},
timeout=60,
)
)
Po stronie serwera weryfikacja mieści się w middleware, który przechwytuje odpowiednie trasy, zanim dotrą do logiki biznesowej:
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)
Co Vibe załatwia za Ciebie
W Vibe wyróżnione konektory — GitHub, Gmail, Linear — mają już podpięte OAuth: użytkownik klika, wyraża zgodę i gotowe. W przypadku własnych konektorów konfiguracja oferuje te same trzy opcje opisane powyżej: Brak uwierzytelniania dla publicznego URL-a, Token, jeśli wklejasz klucz ręcznie, oraz OAuth 2.0 dla pełnego przepływu. Jeden szczegół ma istotne konsekwencje praktyczne: token jest przechowywany na użytkownika, a nie na organizację. W zespole Mistral każdy członek przechodzi więc przez własny proces zgody i pracuje na własnych poświadczeniach — co zapobiega sytuacji, w której odejście kogoś z zespołu lub odwołanie dostępu blokuje dostęp wszystkim.
Kluczowe wnioski
- OAuth 2.0 umożliwia wyraźną zgodę z ograniczonymi prawami (scopes)
- Przepływ: autoryzacja → kod → tokeny (dostępu + odnawiający)
- Stosuj zasadę najmniejszych uprawnień do zakresów
- Tokeny muszą być bezpiecznie przechowywane i automatycznie odnawiane
- W prostych przypadkach wystarczy statyczny token w nagłówkach HTTP
- W Vibe tokeny są przechowywane na użytkownika