Exemplo Completo: Servidor Remoto com Autenticação
Nesta página
Atualização de 2 de novembro de 2026 — Le Chat é agora Vibe. Desde 28 de maio de 2026, o Le Chat foi renomeado para Vibe (ainda em chat.mistral.ai): um único agente para trabalho e código, mantendo 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 são agora competências (invocadas com
@), as memórias servem como base de conhecimento e a pesquisa profunda é a competência Deep Research. Os planos chamam-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: os resultados derun_asyncsão lidos a partir deresult.output_as_text; o SDKmistralai3.7.0 não possui um atributooutput.
Atualização de 2 de novembro de 2026 — MCP Python SDK v2. Este curso segue agora a versão 2 do SDK
mcp(2.3.0 em 2 de outubro de 2026):MCPServersubstituiFastMCP, as definições de transporte movem-se pararun()oustreamable_http_app(), e uma aplicação exposta sob um nome de anfitrião real deve declarar esse nome de anfitrião (transport_security). Esta é também a versão exigida pelo SDK Mistral: o extramistralai[agents]requermcp>=2.2.0,<3.0. Fontes: Novidades na v2 · Guia de Migração · Implementar e escalar.
Cenário: Um Servidor MCP de Gestão de Tarefas
As lições anteriores cobriram as peças individuais: transporte HTTP, middleware e autenticação por token. Agora, vai montá-las num projeto totalmente funcional. O servidor expõe quatro ferramentas de gestão de tarefas — criar, listar, concluir, eliminar — e o cliente liga-se remotamente, apresentando um token bearer em cada pedido. Este mesmo servidor será depois executado a partir do Vibe sem uma única linha de código extra: essa é toda a vantagem de um servidor remoto sobre um servidor STDIO.
O Servidor: task_server.py
Três elementos coexistem neste único ficheiro. O FastAPI gere o transporte HTTP e o middleware de autenticação, o MCPServer gere o protocolo MCP e as ferramentas, e um dicionário Python serve de base de dados. A ordem dos ficheiros importa: declare primeiro o servidor MCP e as suas ferramentas, depois crie a aplicação FastAPI com o lifespan que inicia o gestor de sessão e, por fim, monte o servidor. Note que o middleware protege o caminho /tasks, que é exatamente onde o servidor MCP está montado: estes dois valores devem coincidir, caso contrário, ficará com uma porta aberta ou um caminho bloqueado.
# task_server.py
"""Remote MCP server with token authentication."""
import json
import os
import uuid
from contextlib import asynccontextmanager
from datetime import datetime
from fastapi import FastAPI, Request, HTTPException
from mcp.server.mcpserver import MCPServer
from mcp.server.transport_security import TransportSecuritySettings
# --- Configuration ---
API_TOKEN = "mcp-secret-token-2026"
# --- In-memory database ---
tasks_db: dict[str, dict] = {}
# --- MCP Server ---
mcp = MCPServer("Task Manager")
@mcp.tool()
def create_task(title: str, description: str = "", priority: str = "medium") -> str:
"""Creates a new task in the manager.
Args:
title: Task title (required, max 200 characters)
description: Detailed description (optional)
priority: Priority level: low, medium, high (default: medium)
Returns:
JSON with the ID and details of the created task
"""
task_id = str(uuid.uuid4())[:8]
task = {
"id": task_id,
"title": title[:200],
"description": description,
"priority": priority if priority in ("low", "medium", "high") else "medium",
"status": "open",
"created_at": datetime.now().isoformat(),
}
tasks_db[task_id] = task
return json.dumps({"success": True, "task": task}, ensure_ascii=False)
@mcp.tool()
def list_tasks(status: str = "all", priority: str = "all") -> str:
"""Lists tasks with optional filters.
Args:
status: Filter by status: all, open, completed (default: all)
priority: Filter by priority: all, low, medium, high (default: all)
Returns:
JSON with the list of tasks and the total count
"""
filtered = list(tasks_db.values())
if status != "all":
filtered = [t for t in filtered if t["status"] == status]
if priority != "all":
filtered = [t for t in filtered if t["priority"] == priority]
return json.dumps({
"total": len(filtered),
"tasks": filtered,
}, ensure_ascii=False)
@mcp.tool()
def complete_task(task_id: str) -> str:
"""Marks a task as completed.
Args:
task_id: The unique identifier of the task
Returns:
Confirmation of the update or an error message
"""
if task_id not in tasks_db:
return json.dumps({"error": f"Task {task_id} not found"})
tasks_db[task_id]["status"] = "completed"
tasks_db[task_id]["completed_at"] = datetime.now().isoformat()
return json.dumps({"success": True, "task": tasks_db[task_id]}, ensure_ascii=False)
@mcp.tool()
def delete_task(task_id: str) -> str:
"""Deletes a task from the manager.
Args:
task_id: The unique identifier of the task to delete
Returns:
Confirmation of deletion or an error message
"""
if task_id not in tasks_db:
return json.dumps({"error": f"Task {task_id} not found"})
deleted = tasks_db.pop(task_id)
return json.dumps({"success": True, "deleted_task": deleted["title"]}, ensure_ascii=False)
# --- Mount the MCP server in FastAPI ---
# streamable_http_app() produces the ASGI app for the MCP server.
# Its session manager must be started by the FastAPI lifespan,
# otherwise the server responds but every tool call fails.
@asynccontextmanager
async def lifespan(app: FastAPI):
async with mcp.session_manager.run():
yield
api = FastAPI(title="Task Manager MCP", lifespan=lifespan)
# --- Authentication Middleware ---
@api.middleware("http")
async def auth_middleware(request: Request, call_next):
"""Verifies the token for all /tasks routes."""
if request.url.path.startswith("/tasks"):
auth = request.headers.get("Authorization", "")
if auth != f"Bearer {API_TOKEN}":
raise HTTPException(status_code=401, detail="Invalid token")
return await call_next(request)
# Public hostname (ngrok, production domain) declared to the MCP server
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
securite = TransportSecuritySettings(
allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*", "localhost:*", "127.0.0.1:*"]
)
api.mount("/tasks", mcp.streamable_http_app(transport_security=securite))
if __name__ == "__main__":
import uvicorn
uvicorn.run(api, host="0.0.0.0", port=8000)
Dois detalhes de implementação merecem a sua atenção. Em create_task, o título é truncado para 200 caracteres e a prioridade assume o valor padrão medium se o valor recebido não estiver na lista permitida: o modelo propõe por vezes valores plausíveis mas fora do contrato, e a ferramenta deve manter-se robusta sem falhar. Em complete_task e delete_task, um ID desconhecido não levanta uma exceção, mas devolve uma mensagem de erro em JSON — o modelo pode ler isto, compreender o seu erro e reformular, ao passo que uma falha impediria esse processo.
Iniciar e Expor o Servidor
# Num primeiro terminal, abra o túnel ngrok
ngrok http 8000
# URL público: https://xyz789.ngrok-free.app
# Num segundo terminal, inicie o servidor declarando este nome de anfitrião
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py
O endpoint MCP encontra-se então em https://xyz789.ngrok-free.app/tasks/mcp. Note a composição deste endereço: o URL público fornecido pelo ngrok, seguido do caminho de montagem /tasks e, depois, do sufixo /mcp adicionado pelo SDK. A confusão sobre esta concatenação é a principal causa de falhas de ligação.
O Cliente: client_tasks.py
Do lado do cliente, nada muda em comparação com um servidor local, exceto o tipo de cliente MCP e a adição do cabeçalho de autenticação. O agente, no entanto, recebe instruções que descrevem o seu papel em linguagem natural — isto incentiva-o a confirmar cada ação em vez de encadear chamadas silenciosamente.
# client_tasks.py
"""MCP client for the remote task server with authentication."""
import asyncio
import os
from mistralai.client import Mistral
from mistralai.extra.run.context import RunContext
from mistralai.extra.mcp.streamable_http import (
MCPClientStreamableHTTP,
StreamableHTTPServerParams,
)
API_TOKEN = "mcp-secret-token-2026"
SERVER_URL = "https://xyz789.ngrok-free.app/tasks/mcp"
async def main():
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Create the agent with adapted instructions
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="task-manager",
instructions=(
"You are an intelligent task manager. "
"Use the available tools to create, list, and manage "
"the user's tasks. Respond in English. "
"Confirm every action performed."
),
)
# Configure the remote MCP client with authentication
mcp_client = MCPClientStreamableHTTP(
params=StreamableHTTPServerParams(
url=SERVER_URL,
headers={"Authorization": f"Bearer {API_TOKEN}"},
timeout=30,
)
)
async with RunContext(
agent_id=agent.id,
continue_on_fn_error=True,
) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# Conversation with the manager
conversations = [
"Create a high priority task: Prepare the MCP presentation",
"Create a medium priority task: Review the documentation",
"List all ongoing tasks",
"Mark the first task as completed",
"Show me the remaining tasks",
]
for msg in conversations:
print(f"\n> {msg}")
result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs=msg,
)
print(f"Agent: {result.output_as_text}")
asyncio.run(main())
A sequência de mensagens é deliberada: encadeia duas criações, uma leitura, uma atualização e uma releitura. Este é o cenário mínimo para verificar que o estado sobrevive de uma chamada para a seguinte e que o modelo consegue recuperar o ID de uma tarefa criada anteriormente na conversa. Se a quarta instrução falhar, o seu problema raramente reside no servidor: geralmente decorre de a resposta de list_tasks não tornar os IDs suficientemente visíveis.
Testar no Mistral Vibe
O mesmo endpoint pode ser adicionado diretamente como um conetor personalizado, proporcionando-lhe uma interface de teste sem escrever um cliente. Esta é também a melhor forma de validar as suas docstrings: o Vibe exibe-as tal como estão durante a descoberta, pelo que vê imediatamente o que o modelo terá à sua frente para decidir qual a ferramenta a invocar.
- Aceda ao separador Connectors no Vibe
- Clique em Add Custom Connector
- Introduza Name como
Task Manager, URL comohttps://xyz789.ngrok-free.app/tasks/mcpe escolha Auth: Token, colando depoismcp-secret-token-2026 - Clique em Connect
O Vibe descobre então automaticamente as quatro ferramentas e pode conversar em linguagem natural com o seu próprio servidor.
Organização do Projeto e Próximos Passos
task-mcp-project/
├── task_server.py # MCP server + FastAPI + auth
├── client_tasks.py # Python client with agent
├── requirements.txt # fastapi, uvicorn, mcp>=2.2,<3, mistralai[agents]
└── .env # MISTRAL_API_KEY, API_TOKEN
Esta estrutura funciona para prototipagem, mas duas coisas desqualificam-na para produção. O token em texto simples no código fonte deve ser movido para .env, e o URL do ngrok muda em cada reinício, quebrando todos os conetores configurados. O ngrok continua a ser a ferramenta ideal para validar uma ideia em minutos; a hospedagem permanente, com as suas opções Docker, cloud e Hugging Face Spaces, é o tema da lição 12.
Pontos-chave
- Um servidor remoto combina FastAPI (HTTP) +
MCPServer(MCP) + middleware (autenticação), com o nome de anfitrião público declarado emtransport_security - A autenticação por token é gerida através do cabeçalho
Authorization: Bearer ... - O cliente
MCPClientStreamableHTTPaceita cabeçalhos personalizados para autenticação - O mesmo servidor é utilizável tanto a partir do Python SDK como do Mistral Vibe
- O ngrok permite uma prototipagem rápida antes da implementação em produção