Arquitetura de um Servidor MCP Personalizado
Nesta página
Atualizado a 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.
Conceção de um servidor MCP de produção
Um protótipo MCP cabe num ficheiro de quarenta linhas, o que muitas vezes basta para convencer uma equipa. A passagem para utilização no mundo real muda tudo: várias pessoas chamam o servidor, as ferramentas multiplicam-se, a configuração varia entre ambientes e o ficheiro único torna-se impossível de manter. Esta lição aborda as decisões arquiteturais que impedem de bater nessa parede — escolher uma estrutura, organizar o projeto, gerir configuração e erros, e decidir entre servidores com estado e sem estado.
Escolher a sua estrutura
Em Python, a classe MCPServer do SDK oficial (anteriormente FastMCP) é a ferramenta padrão. Expõe uma API baseada em decoradores e trata do protocolo MCP por si, pelo que um servidor ganha vida em três linhas:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
As equipas de JavaScript e TypeScript dispõem do SDK MCP oficial publicado pela Anthropic. A lógica é comparável, mesmo que a sintaxe difira:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
A escolha depende menos das capacidades e mais do ecossistema onde o seu servidor irá buscar os dados. Um servidor que consulta uma base de dados via SQLAlchemy ou reutiliza scripts de processamento existentes será naturalmente em Python; um servidor suportado por uma aplicação Express existente permanecerá em TypeScript. A tabela abaixo resume as diferenças práticas.
| Critério | MCPServer (SDK Python) | SDK MCP (TypeScript) |
|---|---|---|
| Maturidade | Muito maduro | Maduro |
| Decoradores | @app.tool() | Método server.tool() |
| Transporte HTTP | Integrado (FastAPI) | Integrado (Express) |
| Comunidade | Grande | Grande |
Uma estrutura de projeto duradoura
A estrutura de diretórios recomendada separa quatro responsabilidades: o que o modelo vê (tools/), o que acede aos dados (services/), o que controla o acesso (auth/) e o que descreve o ambiente (config.py, .env).
my-mcp-server/
├── server.py # Ponto de entrada FastAPI + montagem MCP
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Ferramentas de gestão de projetos
│ ├── file_tools.py # Ferramentas de gestão de ficheiros
│ └── search_tools.py # Ferramentas de pesquisa
├── services/
│ ├── __init__.py
│ ├── database.py # Acesso à base de dados
│ └── external_api.py # Chamadas a APIs externas
├── auth/
│ ├── __init__.py
│ └── middleware.py # Middleware de autenticação
├── config.py # Configuração (variáveis de ambiente)
├── Dockerfile # Contentorização
├── requirements.txt # Dependências Python
├── .env # Variáveis de ambiente (não commitadas)
└── tests/
├── test_tools.py
└── test_integration.py
Esta separação tem uma consequência direta e concreta: as suas ferramentas já não contêm chamadas SQL ou HTTP, apenas validação e delegação para um serviço. Pode então testar a lógica de negócio sem passar pelo MCP e trocar de base de dados sem tocar numa única docstring que o modelo vê.
O ponto de entrada: server.py
O ficheiro principal não faz mais do que montar componentes: cria a aplicação FastAPI, empilha middlewares e monta cada servidor MCP na sua própria rota.
# server.py
"""Ponto de entrada do servidor MCP."""
from contextlib import asynccontextmanager
import os
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from mcp.server.transport_security import TransportSecuritySettings
from tools.project_tools import project_mcp
from tools.search_tools import search_mcp
from auth.middleware import AuthMiddleware
# Cada servidor MCP deve iniciar o seu gestor de sessão
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# Aplicação FastAPI
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS para clientes web
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Middleware de autenticação
api.add_middleware(AuthMiddleware)
# Nome de anfitrião público sob o qual os servidores são servidos (caso contrário: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Montar servidores MCP em rotas distintas
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Página inicial (opcional mas útil)
@api.get("/")
async def root():
return {
"service": "My MCP Server",
"version": "1.0.0",
"endpoints": {
"projects": "/projects/mcp",
"search": "/search/mcp",
},
}
if __name__ == "__main__":
import uvicorn
uvicorn.run(api, host="0.0.0.0", port=8000)
Montar em rotas distintas permite aos utilizadores ativar apenas o domínio de que necessitam: alguém à procura de documentação liga-se a /search/mcp sem que lhe sejam oferecidas ferramentas de gestão de projetos. Quanto à página inicial, parece trivial até um colega perguntar pelo URL exato do ponto final; ela responde por si e serve como verificação de saúde.
Um módulo de ferramentas por domínio
Cada ficheiro na pasta tools/ declara o seu próprio objeto MCPServer e agrupa ferramentas do mesmo domínio funcional. Eis o aspeto do módulo de gestão de projetos, importado anteriormente pelo server.py:
# tools/project_tools.py
"""Ferramentas MCP para gestão de projetos."""
from mcp.server.mcpserver import MCPServer
from services.database import db
project_mcp = MCPServer(
"Project Manager",
instructions="Tools for project and task management",
)
@project_mcp.tool()
async def create_project(name: str, description: str = "") -> str:
"""Cria um novo projeto.
Args:
name: Nome do projeto (2-100 caracteres)
description: Descrição do projeto (opcional)
Returns:
JSON com detalhes do projeto criado
"""
project = await db.projects.create(name=name, description=description)
return project.to_json()
@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
"""Lista projetos por estado.
Args:
status: Filtrar por estado: active, archived, all (padrão: active)
Returns:
JSON com lista de projetos
"""
projects = await db.projects.list(status=status)
return projects.to_json()
Repare como os corpos das funções são breves: apenas duas linhas cada, porque o acesso aos dados vive em services/database.py. A ferramenta limita-se a descrever o seu contrato ao modelo e delega.
Configuração centralizada
Qualquer valor que mude entre a sua máquina e o servidor de produção deve vir do ambiente, nunca do código. Um único ficheiro config.py reúne estas variáveis com os seus valores padrão:
# config.py
"""Configuração do servidor MCP."""
import os
from dataclasses import dataclass
@dataclass
class Config:
api_token: str = os.getenv("MCP_API_TOKEN", "")
database_url: str = os.getenv("DATABASE_URL", "sqlite:///data.db")
debug: bool = os.getenv("DEBUG", "false").lower() == "true"
port: int = int(os.getenv("PORT", "8000"))
max_results: int = int(os.getenv("MAX_RESULTS", "50"))
config = Config()
O parâmetro max_results ilustra o benefício desta abordagem: no dia em que uma ferramenta devolver resultados em excesso e saturar o contexto do modelo, ajusta uma variável de ambiente e reinicia, sem necessidade de reimplementar código.
Erros legíveis pelo modelo
Uma exceção Python que sobe abruptamente não diz nada ao modelo: este vê uma falha sem compreender o porquê e, muitas vezes, tenta novamente da mesma forma. Em vez disso, padronize um formato de resposta de erro explícito com um código e uma mensagem.
import json
def error_response(message: str, code: str = "error") -> str:
"""Formata uma mensagem de erro padronizada."""
return json.dumps({
"success": False,
"error": {"code": code, "message": message}
}, ensure_ascii=False)
@project_mcp.tool()
async def get_project(project_id: str) -> str:
"""Recupera detalhes do projeto por ID."""
try:
project = await db.projects.get(project_id)
if not project:
return error_response(f"Project {project_id} not found", "not_found")
return project.to_json()
except Exception as e:
return error_response(f"Server error: {str(e)}", "server_error")
A diferença é decisiva na conversação. Perante not_found, o modelo compreende que deve primeiro listar os projetos para encontrar o ID correto; perante uma exceção silenciosa, desiste ou entra em loop.
Com estado ou sem estado
Um servidor com estado retém informação entre chamadas: base de dados em memória, sessões de utilizador, contexto de trabalho. Isto é comum em servidores de gestão, como o gestor de tarefas da lição anterior. Um servidor sem estado trata cada pedido de forma independente, não recordando nada — recomendado para computação ou transformação puras, permitindo escalabilidade horizontal, já que qualquer instância pode tratar qualquer pedido. O SDK v2 permite isto através de um parâmetro da aplicação HTTP (já não passado ao construtor). Note que, com a especificação de 2026-07-28, o próprio protocolo já não conhece sessões: esta definição diz respeito apenas a clientes que negociam uma versão anterior do protocolo.
app = MCPServer("Stateless Server")
# A definição é passada ao construir a aplicação HTTP
mcp_app = app.streamable_http_app(stateless_http=True)
Decida esta questão antes de escrever as suas ferramentas, não depois: passar de um servidor com estado para um sem estado implica mover todo o estado para uma base de dados externa, o que reescreve uma boa parte do código.
Pontos-chave
- Separe as suas ferramentas em módulos temáticos numa pasta
tools/ - Utilize o FastAPI como base HTTP, monte servidores MCP em rotas dedicadas e passe o seu lifespan
- Centralize a configuração através de variáveis de ambiente
- Padronize os formatos de resposta de erro para que o modelo os possa utilizar
- Escolha entre com estado (gestão de dados) e sem estado (computação pura)
- Adicione uma página inicial
/para documentar os seus pontos finais MCP