Премини към основното съдържание
Български— Изберете език
Меню

OAuth 2.0 за MCP сървъри

Урок 8 от 14 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Защо OAuth в MCP?
  2. Как работи потокът
  3. Конфигуриране на OAuth в Python клиента
  4. Минимални привилегии, приложени към обхватите (scopes)
  5. Съхраняване и подновяване на токени
  6. Когато прост токен е достатъчен
  7. Какво Vibe обработва за Вас
  8. Ключови изводи

Актуализация от 2 ноември 2026 г. — Le Chat вече е Vibe. От 28 май 2026 г. Le Chat беше ребрандиран като Vibe (все още на chat.mistral.ai): единен агент за работа и код, който запазва Вашите разговори, настройки и абонаменти. Legacy изживяването на Le Chat остава достъпно в режим Chat; в режим Work агентите станаха умения (извикват се с @»), спомените вече са база от знания, а дълбокото търсене е умението Deep Research. Плановете вече се наричат Mistral Free, Pro, Team и Enterprise. Този урок използва името Vibe; някои менюта, описани тук, може да са променили имената или местоположенията си. *Добавка от 3 ноември: Предишният пример извикваше requires_auth, set_oauth_paramsилиget_token_from_auth_responseвърхуMCPClientStreamableHTTP, който няма нито един от тези методи в mistralaiSDK 3.7.0; сега следва официалния примерasync_conversation_run_mcp_remote_auth.py, използвайки MCPClientSSE`. Източник: client-python, MCP examples.*

Защо OAuth в MCP?

Докато Вашият MCP сървър само конвертира валути или заявява публична база данни, идентичността не е проблем. Тя става критична в момента, в който сървърът докосне имейли, календари, GitHub хранилища или тикети в Linear: той вече не работи за себе си, а действа от името на конкретен потребител. Статичен токен, седящ в конфигурационен файл, не казва нищо за това съгласие. Той не посочва кой е оторизирал какво, за колко време и докъде се простират предоставените права. OAuth 2.0 адресира точно тези три пропуски: изрично съгласие, права, ограничени от обхвати (scopes), и сигурно подновяване.

Припомнете си трите нива на автентикация, разгледани по-рано. Първото, без автентикация, е подходящо за публичен URL без чувствителни данни. Второто, статичен токен, съответства на API ключ, генериран ръчно, като GitHub Personal Access Token. Третото, OAuth 2.0, добавя пълния поток на съгласие с обхвати и токени за обновяване. Преминаването от второто към третото ниво не е въпрос на техническа сложност, а на отговорност: щом множество хора използват Вашия сървър върху собствените си данни, споделеният токен се превръща в дупка в сигурността.

Как работи потокът

Когато потребител свърже MCP сървър с OAuth във Vibe, се свързват седем стъпки. Струва си да ги визуализирате веднъж завинаги:

1. Потребителят кликва на "Connect" във Vibe
       ↓
2. Vibe пренасочва към страницата за оторизация на услугата
   (напр. GitHub, Google, Linear)
       ↓
3. Потребителят предоставя поисканите разрешения (обхвати/scopes)
       ↓
4. Услугата връща код за оторизация към callback адреса
       ↓
5. Клиентът разменя кода за токен за достъп + токен за обновяване
       ↓
6. Токенът за достъп се използва за всяко MCP извикване
       ↓
7. Когато токенът за достъп изтече, токенът за обновяване получава нов

В тази хореография циркулират три различни токена и те често се бъркат. Кодът за оторизация е временен и еднократен: той се разменя незабавно за истинските токени. Токенът за достъп след това придружава всяка заявка и живее кратко, обикновено един час. Токенът за обновяване накрая служи само за получаване на нов токен за достъп, без да се иска отново съгласие от потребителя. Този кратък живот на токена за достъп е предпазна мярка: ако токен изтече, прозорецът му на експлоатация остава тесен.

Конфигуриране на OAuth в Python клиента

Mistral SDK поддържа този поток с помощника build_oauth_params и няколко метода на MCP клиента. Следете избора си на клиент: в mistralai SDK 3.7.0 тези OAuth методи съществуват само в SSE клиента, MCPClientSSE, който официалният пример на SDK използва със сървъра Linear; MCPClientStreamableHTTP няма нито един от тях.

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  # Сървърът е отворен: няма какво да се прави

    # 1. Откриване на OAuth крайните точки на сървъра
    #    (и динамична регистрация на клиента, ако не е предоставен 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. Изграждане на URL за съгласие и отварянето му в браузъра
    login_url, state = await mcp_client.get_auth_url_and_state(REDIRECT_URL)
    print(f"Оторизирайте достъпа: {login_url}")

    # 3. Прихващане на callback, след това размяна на кода за токен,
    #    използвайки клиент, пресъздаден от запазените OAuth параметри
    auth_response = await wait_for_callback()  # малък локален 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 прави две неща и само две неща: чете OAuth метаданните, публикувани от MCP сървъра, и динамично регистрира клиент, ако не предадете нито client_id, нито client_secret. Останалата част от потока е Ваша грижа — отваряне на URL адреса за съгласие, събиране на callback на Вашия redirect_url порт, размяна на кода за токен. SDK не скрива тези стъпки; то ги инструментира и точно това разбиване Ви позволява да свържете callback към уеб приложение, а не към скрипт.

Минимални привилегии, приложени към обхватите (scopes)

Обхватите дефинират какво може да прави Вашият сървър, след като бъде дадено съгласието, и екранът за съгласие ги показва на потребителя. Изкушаващо е да искате широко: това избягва връщане назад, ако възникне нужда. Това обаче е и най-добрият начин да изплашите предпазлив потребител и ненужно да изложите акаунта му на риск. Сравнете:

# Лошо: твърде много разрешения
scope=["repo", "admin:org", "delete_repo", "user"]

# Добре: точно достатъчно за създаване на_issues
scope=["repo:issues", "read:user"]

Сървър, който създава_issues, няма причина да изтрива хранилища или да администрира организацията. Всяка услуга публикува своя собствена номенклатура на обхватите: консултирайте се с OAuth документацията на целевата услуга, вместо да гадаете по аналогия.

Съхраняване и подновяване на токени

Токените, които получавате, струват колкото удостоверителните данни, които заменят, и заслужават същото внимание. Запишете ги в специализиран файл с ограничени системни разрешения:

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):
    """Запазване на токени сигурно."""
    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))
    # Ограничаване на файловите разрешения
    os.chmod(TOKEN_FILE, 0o600)

chmod към 0o600 не е декоративен: без него, на споделена машина, всеки акаунт може да прочете Вашите токени. Подновяването междувременно се свежда до POST извикване към token_url на услугата с токена за обновяване в ръка. Потребителят не вижда нищо да преминава, което е точно целта:

import httpx

async def refresh_access_token(
    token_url: str,
    client_id: str,
    client_secret: str,
    refresh_token: str,
) -> dict:
    """Подновяване на токена за достъп чрез токена за обновяване."""
    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()

Когато прост токен е достатъчен

Не всеки сървър оправдава този механизъм. За вътрешен инструмент, използван от шепа разработчици, API ключ, предаден в HTTP хедър, работи съвсем добре, и MCP клиентът го приема директно:

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

# Сървър с прост токен
mcp_client = MCPClientStreamableHTTP(
    params=StreamableHTTPServerParams(
        url="https://my-server.com/mcp",
        headers={"Authorization": "Bearer my_secret_api_token"},
        timeout=60,
    )
)

От страна на сървъра, проверката се побира в middleware, който прихваща съответните маршрути, преди да достигнат до Вашата бизнес логика:

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)

Какво Vibe обработва за Вас

Във Vibe, представените конектори — GitHub, Gmail, Linear — идват с вече свързан OAuth: потребителят кликва, дава съгласие и готово. За Вашите персонализирани конектори конфигурацията предлага същите три опции, описани по-горе: Без автентикация за публичен URL, Токен, ако поставите ключа на ръка, и OAuth 2.0 за пълния поток. Един детайл има важни практически последствия: токенът се съхранява на потребител, а не на организация. В екип на Mistral всеки член следователно преминава през собственото си съгласие и работи със собствените си удостоверителни данни — което предотвратява напускане или отмяна да прекъсне достъпа за всички.

Ключови изводи

  • OAuth 2.0 позволява изрично съгласие с ограничени права (обхвати/scopes)
  • Потокът: оторизация → код → токени (достъп + обновяване)
  • Приложете принципа на минималните привилегии към обхватите
  • Токените трябва да се съхраняват сигурно и да се подновяват автоматично
  • За прости случаи е достатъчен статичен токен в HTTP хедъри
  • Във Vibe токените се съхраняват на потребител