OAuth 2.0 para servidores MCP
Nesta página
Atualização de 2 de novembro de 2026 — O Le Chat é agora o Vibe. Desde 28 de maio de 2026, o Le Chat foi rebatizado como Vibe (ainda em chat.mistral.ai): um único agente para trabalho e código, que mantém as suas conversas, definições e subscrições. A experiência legada do Le Chat permanece acessível no modo Chat; no modo Work, os agentes tornaram-se competências (invocadas com
@), as memórias são agora a base de conhecimento e a pesquisa profunda é a competência Deep Research. Os planos denominam-se agora Mistral Free, Pro, Team e Enterprise. Esta lição utiliza o nome Vibe; alguns menus aqui descritos podem ter alterado de nome ou localização. Adenda de 3 de novembro: O exemplo anterior invocavarequires_auth,set_oauth_paramsouget_token_from_auth_responseemMCPClientStreamableHTTP, que não possui nenhum destes métodos no SDKmistralai3.7.0; segue agora o exemplo oficialasync_conversation_run_mcp_remote_auth.py, utilizandoMCPClientSSE. Fonte: client-python, exemplos MCP.
Por que razão usar OAuth no MCP?
Enquanto o seu servidor MCP apenas converter moedas ou consultar uma base de dados pública, a identidade não é um problema. Torna-se crítico no momento em que o servidor acede a e-mails, calendários, repositórios GitHub ou tickets Linear: deixa de funcionar por si próprio e passa a atuar em nome de um utilizador específico. Um token estático num ficheiro de configuração não diz nada sobre este consentimento. Não indica quem autorizou o quê, por quanto tempo, nem até onde se estendem os direitos concedidos. O OAuth 2.0 colmata exatamente estas três lacunas: consentimento explícito, direitos limitados por âmbitos (scopes) e renovação segura.
Recorde os três níveis de autenticação abordados anteriormente. O primeiro, sem autenticação, adequa-se a um URL público sem dados sensíveis. O segundo, token estático, corresponde a uma chave de API gerada manualmente, como um Personal Access Token do GitHub. O terceiro, OAuth 2.0, adiciona todo o fluxo de consentimento com âmbitos e tokens de atualização. Passar do segundo para o terceiro nível não é uma questão de sofisticação técnica, mas de responsabilidade: assim que várias pessoas utilizam o seu servidor com os seus próprios dados, um token partilhado torna-se uma falha de segurança.
Como funciona o fluxo
Quando um utilizador liga um servidor MCP com OAuth no Vibe, sete passos encadeiam-se. Vale a pena visualizá-los de uma vez por todas:
1. Utilizador clica em "Connect" no Vibe
↓
2. Vibe redireciona para a página de autorização do serviço
(ex.: GitHub, Google, Linear)
↓
3. Utilizador concede as permissões solicitadas (scopes)
↓
4. Serviço devolve um código de autorização ao callback
↓
5. Cliente troca o código por um token de acesso + token de atualização
↓
6. Token de acesso é usado em cada chamada MCP
↓
7. Quando o token de acesso expira, o token de atualização obtém um novo
Três tokens diferentes circulam nesta coreografia e são frequentemente confundidos. O código de autorização é temporário e de uso único: é trocado imediatamente pelos tokens reais. O token de acesso acompanha depois cada pedido e tem vida curta, tipicamente uma hora. O token de atualização, finalmente, serve apenas para obter um novo token de acesso sem pedir novamente o consentimento ao utilizador. Esta curta duração do token de acesso é uma salvaguarda: se um token vazar, a sua janela de exploração permanece reduzida.
Configurar o OAuth no cliente Python
O SDK Mistral suporta este fluxo com o auxiliar build_oauth_params e alguns métodos do cliente MCP. Atenção à escolha do seu cliente: no SDK mistralai 3.7.0, estes métodos OAuth existem apenas no cliente SSE, MCPClientSSE, que é o que o exemplo oficial do SDK utiliza com o servidor Linear; MCPClientStreamableHTTP não possui nenhum deles.
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 # Servidor aberto: nada a fazer
# 1. Descobrir os endpoints OAuth do servidor
# (e registar dinamicamente o cliente se nenhum client_id for fornecido)
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 o URL de consentimento e abri-lo no navegador
login_url, state = await mcp_client.get_auth_url_and_state(REDIRECT_URL)
print(f"Autorizar acesso: {login_url}")
# 3. Captar o callback e trocar o código por um token,
# usando um cliente recriado a partir dos parâmetros OAuth guardados
auth_response = await wait_for_callback() # pequeno 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 faz duas coisas e apenas duas: lê os metadados OAuth publicados pelo servidor MCP e regista dinamicamente um cliente se não passar nem client_id nem client_secret. O resto do fluxo depende de si — abrir o URL de consentimento, recolher o callback na porta do seu redirect_url, trocar o código por um token. O SDK não esconde estes passos; fornece as ferramentas para os executar, e é precisamente esta decomposição que lhe permite integrar o callback numa aplicação web em vez de num script.
Privilégio mínimo, aplicado aos âmbitos (scopes)
Os âmbitos definem o que o seu servidor pode fazer uma vez dado o consentimento, e o ecrã de consentimento exibe-os ao utilizador. Pedir amplamente é tentador: evita recuar se surgir uma necessidade. É também a melhor forma de assustar um utilizador cauteloso e expor desnecessariamente a sua conta. Compare:
# Mau: demasiadas permissões
scope=["repo", "admin:org", "delete_repo", "user"]
# Bom: apenas o suficiente para criar issues
scope=["repo:issues", "read:user"]
Um servidor que cria issues não tem razão para apagar repositórios ou administrar a organização. Cada serviço publica a sua própria nomenclatura de âmbitos: consulte a documentação OAuth do serviço alvo em vez de adivinhar por analogia.
Guardar e renovar tokens
Os tokens que obtém valem as credenciais que substituem e merecem o mesmo cuidado. Escreva-os num ficheiro dedicado com permissões de sistema restritas:
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 em segurança."""
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 permissões do ficheiro
os.chmod(TOKEN_FILE, 0o600)
O chmod para 0o600 não é decorativo: sem ele, numa máquina partilhada, qualquer conta pode ler os seus tokens. A renovação, entretanto, resume-se a uma chamada POST ao token_url do serviço com o token de atualização na mão. O utilizador não vê nada a passar, que é exatamente o objetivo:
import httpx
async def refresh_access_token(
token_url: str,
client_id: str,
client_secret: str,
refresh_token: str,
) -> dict:
"""Renovar o token de acesso através do token de atualização."""
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()
Quando um token simples basta
Nem todos os servidores justificam esta maquinaria. Para uma ferramenta interna consumida por um punhado de programadores, uma chave de API passada num cabeçalho HTTP funciona perfeitamente, e o cliente MCP aceita-a diretamente:
from mistralai.extra.mcp.streamable_http import (
MCPClientStreamableHTTP,
StreamableHTTPServerParams,
)
# Servidor com token simples
mcp_client = MCPClientStreamableHTTP(
params=StreamableHTTPServerParams(
url="https://my-server.com/mcp",
headers={"Authorization": "Bearer my_secret_api_token"},
timeout=60,
)
)
Do lado do servidor, a verificação encaixa num middleware que interceta as rotas relevantes antes de chegarem à sua lógica de negócio:
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)
O que o Vibe trata por si
No Vibe, os conectores em destaque — GitHub, Gmail, Linear — vêm com o OAuth já configurado: o utilizador clica, consente e está feito. Para os seus conectores personalizados, a configuração oferece as mesmas três opções descritas acima: Sem autenticação para um URL público, Token se colar a chave manualmente e OAuth 2.0 para o fluxo completo. Um detalhe tem consequências práticas importantes: o token é guardado por utilizador, não por organização. Numa equipa Mistral, cada membro passa, portanto, pelo seu próprio consentimento e trabalha com as suas próprias credenciais — o que impede que uma saída ou revogação quebre o acesso a todos.
Pontos-chave
- OAuth 2.0 permite consentimento explícito com direitos limitados (âmbitos)
- O fluxo: autorização → código → tokens (acesso + atualização)
- Aplique o princípio do privilégio mínimo aos âmbitos
- Os tokens devem ser guardados em segurança e renovados automaticamente
- Para casos simples, um token estático em cabeçalhos HTTP é suficiente
- No Vibe, os tokens são guardados por utilizador