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

Arquitetura de um Servidor MCP Personalizado

Aula 10 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Conceção de um servidor MCP de produção
  2. Escolher a sua estrutura
  3. Uma estrutura de projeto duradoura
  4. O ponto de entrada: server.py
  5. Um módulo de ferramentas por domínio
  6. Configuração centralizada
  7. Erros legíveis pelo modelo
  8. Com estado ou sem estado
  9. Pontos-chave

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): 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.

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érioMCPServer (SDK Python)SDK MCP (TypeScript)
MaturidadeMuito maduroMaduro
Decoradores@app.tool()Método server.tool()
Transporte HTTPIntegrado (FastAPI)Integrado (Express)
ComunidadeGrandeGrande

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