Configurar um Servidor MCP Local (STDIO)
Nesta página
Atualizado em 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 Mistral SDK: o extramistralai[agents]requermcp>=2.2.0,<3.0. Fontes: Novidades na v2 · Guia de Migração · Implementar e escalar.
O seu primeiro servidor MCP local
O modo STDIO é o ponto de partida natural para desenvolver e testar um servidor MCP: tudo corre na sua máquina, sem implementação, sem URL pública e sem certificados para gerir. Edita um ficheiro, reinicia e observa. Nesta lição, vai escrever um servidor MCP local em Python e, em seguida, ligá-lo a um cliente.
Quanto aos pré-requisitos, precisa do Python 3.10 ou superior, de um pip atualizado e, de preferência, de um ambiente virtual dedicado. Este último ponto não é cosmético: os pacotes MCP evoluem rapidamente, e um venv separado por projeto impede que quebre um servidor funcional ao instalar uma dependência para outro.
# Criar um ambiente virtual
python -m venv mcp-env
source mcp-env/bin/activate # Linux/Mac
# mcp-env\Scripts\activate # Windows
# SDK MCP oficial (v2) e Mistral SDK com o seu extra de agentes
pip install "mcp[cli]>=2.2,<3" "mistralai[agents]"
Escrever o servidor
Com MCPServer, a classe de alto nível no SDK oficial (anteriormente FastMCP), um servidor local requer apenas algumas linhas. Instancia uma aplicação atribuindo-lhe um nome descritivo e, em seguida, decora as suas funções Python com @app.tool() para as expor.
# serveur_local.py
from mcp.server.mcpserver import MCPServer
# Inicializar o servidor com um nome descritivo
app = MCPServer("Local Demo Server")
@app.tool()
def greet(name: str) -> str:
"""Greets a person by name.
Args:
name: The first name of the person to greet
Returns:
A personalized greeting message
"""
return f"Hello {name}! Welcome to the world of MCP."
@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
"""Performs a simple mathematical calculation.
Args:
operation: The operation to perform (add, sub, mul, div)
a: First number
b: Second number
Returns:
The result of the calculation
"""
ops = {
"add": a + b,
"sub": a - b,
"mul": a * b,
"div": a / b if b != 0 else "Error: division by zero"
}
result = ops.get(operation, "Unknown operation")
return f"{a} {operation} {b} = {result}"
Este ficheiro expõe duas ferramentas. Note o papel das docstrings: elas não servem apenas para documentar o seu código para um colega; tornam-se literalmente na descrição que o modelo lê para decidir se chama calculate em vez de greet. Uma docstring descuidada aqui leva a chamadas erráticas mais tarde.
Configurar o cliente STDIO
Do lado do cliente, não está a ligar-se a um endereço; está a explicar como iniciar o servidor. É essa a função de StdioServerParameters.
# client_stdio.py
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from pathlib import Path
# Caminho para o seu servidor
path_to_server = Path("serveur_local.py")
# Configuração do servidor STDIO
server_params = StdioServerParameters(
command="python", # O comando para lançar o servidor
args=[str(path_to_server)], # Os argumentos (o ficheiro Python)
env=None, # Variáveis de ambiente (opcional)
)
# Criar o cliente MCP
mcp_client = MCPClientSTDIO(stdio_params=server_params)
Três parâmetros merecem detalhe.
command
Este é o comando do sistema que lança o processo do servidor: "python" para um servidor Python, "node" para um servidor JavaScript, ou o caminho direto para um binário se o seu servidor estiver compilado.
# Python
command="python"
# Node.js
command="node"
# Um executável compilado
command="./mon_serveur_mcp"
args
Esta é a lista de argumentos passados a esse comando. Para um script Python, isto é, no mínimo, o caminho do ficheiro, mas nada o impede de passar aqui as opções do seu servidor.
# Script simples
args=["serveur_local.py"]
# Com argumentos adicionais
args=["serveur_local.py", "--port", "8080", "--verbose"]
env
Este é o dicionário de variáveis de ambiente passadas ao processo do servidor: o canal através do qual lhe passa uma chave de API, um URL de base de dados ou uma flag de depuração.
import os
server_params = StdioServerParameters(
command="python",
args=["serveur_local.py"],
env={
**os.environ, # Herdar do ambiente atual
"API_KEY": "your_api_key",
"DATABASE_URL": "postgresql://...",
"DEBUG": "true",
},
)
O comportamento deste parâmetro surpreende frequentemente as pessoas. Com env=None, o servidor herda todo o ambiente do processo pai; com um dicionário, vê estritamente apenas as variáveis listadas. Se fornecer um dicionário sem despejar os.environ nele, não se surpreenda se o seu servidor deixar de encontrar o seu PATH ou a sua chave de API: o comportamento é perfeitamente lógico, simplesmente radical.
Testar antes de integrar
Antes de ligar o seu servidor a um agente, teste-o isoladamente com o MCP Inspector. O raciocínio é simples: se uma chamada falhar assim que o servidor estiver ligado a um modelo, não saberá se o problema reside no seu código ou na decisão do modelo. O Inspector remove esta ambiguidade.
npx @modelcontextprotocol/inspector python serveur_local.py
O comando abre uma interface web local onde pode listar as ferramentas expostas, inspecionar a descrição e os parâmetros que o modelo receberá, acionar uma chamada manual com argumentos à sua escolha e verificar o formato exato do valor de retorno. Crie o hábito de usar isto sistematicamente: são cinco minutos que poupam uma hora.
Finalmente, eis uma organização de ficheiros que envelhece bem, com o servidor, o cliente, dependências, segredos mantidos fora do repositório e testes unitários para as suas ferramentas:
mon-projet-mcp/
├── serveur_local.py # O servidor MCP
├── client_stdio.py # O script do cliente
├── requirements.txt # Dependências
├── .env # Variáveis de ambiente (nunca committed)
└── tests/
└── test_tools.py # Testes unitários para ferramentas
Pontos-chave
- Um servidor STDIO é lançado como um processo local
StdioServerParametersconfigura o comando, os argumentos e as variáveis de ambiente- As docstrings das suas ferramentas servem de descrição para o modelo
- O MCP Inspector (
npx @modelcontextprotocol/inspector) é essencial para testes env=Noneherda todo o ambiente; um dict explícito limita as variáveis