Przejdź do głównej treści
Polski— Wybierz język
Menu

OAuth 2.0 dla serwerów MCP

Lekcja 8 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Dlaczego OAuth w MCP?
  2. Jak działa przepływ
  3. Konfiguracja OAuth w kliencie Pythona
  4. Minimalne uprawnienia zastosowane do zakresów (scopes)
  5. Przechowywanie i odnawianie tokenów
  6. Kiedy prosty token wystarczy
  7. Co Vibe załatwia za Ciebie
  8. Kluczowe wnioski

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ł metody requires_auth, set_oauth_params lub get_token_from_auth_response na obiekcie MCPClientStreamableHTTP, który nie posiada żadnej z tych metod w SDK mistralai w wersji 3.7.0; obecnie przykład podąża za oficjalnym wzorcem async_conversation_run_mcp_remote_auth.py, używając MCPClientSSE. Ź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