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

Configurar um Servidor MCP Local (STDIO)

Aula 4 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. O seu primeiro servidor MCP local
  2. Escrever o servidor
  3. Configurar o cliente STDIO
  4. Testar antes de integrar
  5. Pontos-chave

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): 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 Mistral SDK: o extra mistralai[agents] requer mcp>=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
  • StdioServerParameters configura 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=None herda todo o ambiente; um dict explícito limita as variáveis