Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Configurar um Servidor MCP Remoto via SSE

Aula 7 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Da Local para a Remota
  2. O Servidor Quase Não Se Altera
  3. Obter um URL Público com o ngrok
  4. Ligar um Cliente Python
  5. Múltiplos Servidores num Único Anfitrião
  6. Pontos-chave

Atualização de 2 de novembro de 2026 — Le Chat passa a chamar-se 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 disponível no modo Chat; no modo Work, os agentes são agora competências (invocadas com @), as memórias funcionam como base de conhecimento e a pesquisa profunda é a competência Deep Research. Os planos designam-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 de run_async são lidos através de result.output_as_text; o SDK mistralai 3.7.0 não possui o atributo output.

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): MCPServer substitui FastMCP, as definições de transporte movem-se para run() ou streamable_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 da Mistral: o extra mistralai[agents] requer mcp>=2.2.0,<3.0. Fontes: Novidades na v2 · Guia de Migração · Implementar e escalar.

Da Local para a Remota

Até agora, o seu servidor MCP residia na sua máquina, comunicando via STDIO. Este modo é ideal para desenvolvimento, mas isola o seu trabalho: mais ninguém o pode utilizar, e o Vibe da Mistral nunca poderá iniciar um processo na sua máquina local. Para ultrapassar esta barreira, tem de expor o servidor através de HTTP.

A alteração é mais ligeira do que possa pensar. Um servidor MCP remoto publica as suas ferramentas num URL; o cliente — seja o Vibe, um SDK ou um IDE — liga-se através da rede em vez de gerar um processo. O seu código de ferramenta permanece inalterado.

O Servidor Quase Não Se Altera

O MCPServer suporta nativamente o transporte HTTP Streamable. O ficheiro abaixo está escrito exatamente como um servidor local: mesmos decoradores, mesmas docstrings, mesmas assinaturas tipadas.

# remote_server.py
"""Remote MCP server with HTTP transport."""

from mcp.server.mcpserver import MCPServer

# The server is the same as local
app = MCPServer("Remote Demo Server")

@app.tool()
def analyze_text(text: str, language: str = "fr") -> str:
    """Analyze text and return statistics.

    Args:
        text: The text to analyze
        language: Language code (fr, en, es). Default: fr

    Returns:
        Text statistics: word count, character count, sentence count
    """
    words = len(text.split())
    chars = len(text)
    sentences = text.count(".") + text.count("!") + text.count("?")
    return (
        f"Language: {language}\n"
        f"Words: {words}\n"
        f"Characters: {chars}\n"
        f"Sentences: {sentences}"
    )

@app.tool()
def summarize_key_points(text: str, max_points: int = 5) -> str:
    """Extract key points from text (simplified version).

    Args:
        text: The source text
        max_points: Maximum number of points to extract (1-10)

    Returns:
        List of identified key points
    """
    sentences = [s.strip() for s in text.split(".") if len(s.strip()) > 20]
    points = sentences[:max_points]
    return "\n".join(f"- {p}" for p in points) if points else "No key points identified."

A única alteração é um bloco de arranque adicionado ao final do ficheiro: transporte HTTP, porta e a lista de nomes de anfitrião que o servidor aceita.

import os
from mcp.server.transport_security import TransportSecuritySettings

if __name__ == "__main__":
    # Public hostname, e.g., the one ngrok assigns you (without https://)
    public_host = os.environ.get("MCP_PUBLIC_HOST")
    hosts = ["localhost:*", "127.0.0.1:*"]
    if public_host:
        hosts += [public_host, f"{public_host}:*"]
    app.run(
        transport="streamable-http",
        port=8000,
        transport_security=TransportSecuritySettings(allowed_hosts=hosts),
    )
python remote_server.py

O seu servidor escuta agora em http://localhost:8000/mcp. A lista allowed_hosts não é um pormenor: por predefinição, o SDK v2 apenas aceita pedidos endereçados a localhost ou 127.0.0.1, uma proteção contra DNS rebinding. Por detrás de um túnel ou de um nome de domínio real, qualquer outro pedido recebe um erro 421 Invalid Host header, que o cliente apresenta como um erro de transporte genérico; apenas o registo do servidor revela a razão.

Obter um URL Público com o ngrok

Para testar o seu servidor a partir do Vibe sem uma implementação completa, o ngrok cria um túnel entre um URL público e a sua porta local. Esta ferramenta encurta o ciclo de desenvolvimento mais do que qualquer outra: modifica uma ferramenta, reinicia, e o conetor remoto vê imediatamente a nova versão.

# Install the ngrok agent from https://ngrok.com/download, then authenticate (once)
ngrok config add-authtoken YOUR_NGROK_TOKEN

# Expose port 8000
ngrok http 8000

O ngrok atribui-lhe um endereço como https://abc123.ngrok-free.app. Reinicie o servidor declarando este nome de anfitrião (MCP_PUBLIC_HOST=abc123.ngrok-free.app python remote_server.py). O seu endpoint MCP torna-se nisto, bastando anexar o caminho /mcp:

https://abc123.ngrok-free.app/mcp

Adicione este URL tal como está ao Mistral Vibe como um conetor personalizado. Lembre-se de que é temporário e expõe a sua máquina: não deixe um túnel aberto num servidor que toque em dados reais.

Ligar um Cliente Python

Do lado do cliente, a estrutura do código permanece a mesma da lição RunContext. Apenas a classe de ligação difere: MCPClientStreamableHTTP com StreamableHTTPServerParams substitui o par STDIO, e fornece um URL em vez de um comando.

# remote_client.py
import asyncio
from mistralai.client import Mistral
from mistralai.extra.run.context import RunContext
from mistralai.extra.mcp.streamable_http import (
    MCPClientStreamableHTTP,
    StreamableHTTPServerParams,
)

async def main():
    client = Mistral(api_key="YOUR_API_KEY")

    agent = client.beta.agents.create(
        model="mistral-medium-latest",
        name="remote-assistant",
        instructions="You use remote tools to analyze text.",
    )

    # Connect to the remote server
    server_url = "https://abc123.ngrok-free.app/mcp"
    mcp_client = MCPClientStreamableHTTP(
        params=StreamableHTTPServerParams(
            url=server_url,
            timeout=100,  # Timeout in seconds
        )
    )

    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)

        result = await client.beta.conversations.run_async(
            run_ctx=run_ctx,
            inputs="Analyze this text: MCP is an open protocol.",
        )
        print(result.output_as_text)

asyncio.run(main())

O parâmetro timeout merece uma reflexão. Via STDIO, as chamadas eram quase instantâneas; através da rede, uma ferramenta que consulta uma API de terceiros ou processa um documento grande pode levar várias dezenas de segundos. Um timeout demasiado curto manifesta-se como erros intermitentes, difíceis de reproduzir, geralmente nos pedidos mais úteis.

Quando o servidor espera cabeçalhos específicos — um token de API, uma chave de encaminhamento, uma restrição CORS — passa-os em headers:

mcp_client = MCPClientStreamableHTTP(
    params=StreamableHTTPServerParams(
        url="https://my-server.example.com/mcp",
        timeout=100,
        headers={
            "Authorization": "Bearer my_api_token",
            "X-Custom-Header": "value",
        },
    )
)

Múltiplos Servidores num Único Anfitrião

A Lição 3 recomendou servidores focados em vez de um catálogo universal. Esta recomendação não o condena a alugar uma máquina por servidor: com o FastAPI, pode montar múltiplos servidores MCP em rotas distintas do mesmo anfitrião.

# server.py — Multiple MCP servers on a single host
from contextlib import asynccontextmanager

from fastapi import FastAPI
from mcp.server.mcpserver import MCPServer
from mcp.server.transport_security import TransportSecuritySettings

# MCP server for text analysis
text_mcp = MCPServer("Text Analysis")

@text_mcp.tool()
def analyze(text: str) -> str:
    """Analyze text."""
    return f"Words: {len(text.split())}"

# MCP server for calculations
math_mcp = MCPServer("Math Tools")

@math_mcp.tool()
def calculate(expression: str) -> str:
    """Evaluate a mathematical expression."""
    return str(eval(expression))  # Warning: eval in production!

# Each MCP server produces a standalone ASGI app,
# which must know the hostname under which it is served
security = TransportSecuritySettings(allowed_hosts=["mon-serveur.com", "mon-serveur.com:*"])
text_app = text_mcp.streamable_http_app(transport_security=security)
math_app = math_mcp.streamable_http_app(transport_security=security)

# Combined lifespan: each server must start its session manager
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with text_mcp.session_manager.run(), math_mcp.session_manager.run():
        yield

api = FastAPI(lifespan=lifespan)
api.mount("/text", text_app)
api.mount("/math", math_app)

Obtém dois endpoints independentes, https://mon-serveur.com/text/mcp para ferramentas de análise de texto e https://mon-serveur.com/math/mcp para ferramentas matemáticas, que adiciona separadamente no Vibe. O ponto crítico é o lifespan: cada servidor MCP possui um gestor de sessão que deve ser iniciado explicitamente. Se montar as aplicações sem passar este lifespan ao FastAPI, o servidor responde, mas cada chamada de ferramenta falha com um erro de tarefa não inicializada. Um utilizador que só necessite de cálculos não poluirá o seu contexto com ferramentas de texto. O comentário sobre eval não é brincadeira: num endpoint público, esta linha executa qualquer código enviado pelo chamador — é um exemplo pedagógico, nunca um padrão de produção.

Um último reflexo: antes de adicionar o seu URL a um chat, execute-o novamente através do Inspector. Um endpoint remoto adiciona fontes de falha que o local ignorava — túnel fechado, cabeçalho em falta, porta ocupada — e é melhor descobri-las fora de uma conversa.

Pontos-chave

  • Um servidor MCP remoto expõe as suas ferramentas via HTTP num endpoint /mcp
  • O ngrok permite obter um URL público para desenvolvimento
  • MCPClientStreamableHTTP com StreamableHTTPServerParams liga o cliente ao servidor remoto (MCPClientSSE serve agora apenas para endpoints legados /sse)
  • O parâmetro timeout é importante para servidores lentos
  • Pode montar múltiplos servidores MCP no mesmo anfitrião FastAPI, desde que passe o seu lifespan
  • Teste sempre com o Inspector antes de integrar num chat