Construindo um Servidor MCP com o SDK Python

O SDK oficial Python do MCP oferece um pequeno conjunto de decoradores para registrar ferramentas, recursos e prompts.

Todo o resto, como a conexão, negociação de capacidades e roteamento de requisições, é tratado para você.

Resumo

Um servidor MCP em Python é construído em torno do FastMCP, a classe de servidor de alto nível do SDK.

Você registra capacidades com três decoradores: @mcp.tool(), @mcp.resource() e @mcp.prompt().

As dicas de tipo em cada função servem como o esquema de entrada que o cliente vê durante a negociação de capacidades.

Erros levantados dentro de um manipulador são convertidos em respostas de erro estruturadas em vez de travar o servidor.

Esta página se baseia no esqueleto mínimo da página de noções básicas e aprofunda em argumentos tipados, recursos parametrizados e tratamento de erros.

Receita

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("tickets-server")
 
@mcp.tool()
def create_ticket(title: str, priority: str = "normal") -> str:
    """Cria um ticket de suporte e retorna seu ID."""
    return "T-1042"
 
@mcp.resource("tickets://{ticket_id}")
def get_ticket(ticket_id: str) -> str:
    """Busca um único ticket por ID."""
    return f"Ticket {ticket_id}: aberto"
 
@mcp.prompt()
def triage_prompt(ticket_id: str) -> str:
    return f"Revise o ticket {ticket_id} e recomende um próximo passo."
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

Quando usar isso:

• Você deseja expor uma API interna, banco de dados ou sistema de arquivos para o Claude como ferramentas chamáveis.
• Você precisa de dados somente leitura (configuração, documentação, registros) disponíveis para um cliente sem que isso conte como uma "ação".
• Você deseja modelos de prompt reutilizáveis compartilhados entre todos os clientes que se conectam a este servidor.
• Você está construindo primeiro para desenvolvimento local; stdio é o transporte correto antes de adicionar uma camada de rede.

Exemplo de Trabalho

from dataclasses import dataclass
from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("tickets-server")
 
@dataclass
class Ticket:
    id: str
    title: str
    priority: str
    status: str
 
_tickets: dict[str, Ticket] = {
    "T-1": Ticket(id="T-1", title="Impressora offline", priority="low", status="open"),
    "T-2": Ticket(id="T-2", title="Queda de VPN", priority="high", status="closed"),
}
_next_id = 3
 
 
@mcp.tool()
def create_ticket(title: str, priority: str = "normal") -> str:
    """Cria um novo ticket de suporte e retorna seu ID.
 
    priority deve ser um de: low, normal, high.
    """
    global _next_id
    if priority not in ("low", "normal", "high"):
        raise ValueError(f"prioridade inválida '{priority}', esperado low, normal ou high")
 
    ticket_id = f"T-{_next_id}"
    _next_id += 1
    _tickets[ticket_id] = Ticket(id=ticket_id, title=title, priority=priority, status="open")
    return ticket_id
 
 
@mcp.tool()
def close_ticket(ticket_id: str) -> str:
    """Marca um ticket como fechado."""
    ticket = _tickets.get(ticket_id)
    if ticket is None:
        raise ValueError(f"nenhum ticket com id '{ticket_id}'")
    ticket.status = "closed"
    return f"{ticket_id} fechado"
 
 
@mcp.resource("tickets://{ticket_id}")
def get_ticket(ticket_id: str) -> str:
    """Busca os detalhes de um único ticket por ID."""
    ticket = _tickets.get(ticket_id)
    if ticket is None:
        raise ValueError(f"nenhum ticket com id '{ticket_id}'")
    return f"{ticket.id} [{ticket.priority}] {ticket.title} - {ticket.status}"
 
 
@mcp.resource("tickets://open")
def list_open_tickets() -> str:
    """Lista todos os tickets abertos."""
    open_ids = [t.id for t in _tickets.values() if t.status == "open"]
    return "\n".join(open_ids) if open_ids else "nenhum ticket aberto"
 
 
@mcp.prompt()
def triage_prompt(ticket_id: str) -> str:
    """Constrói um prompt pedindo uma recomendação de triagem para um ticket."""
    return f"Revise o ticket {ticket_id} e recomende se deve ser escalado ou fechado."
 
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

O que isso demonstra:

• Duas ferramentas, create_ticket e close_ticket, que modificam o estado do lado do servidor e validam sua própria entrada antes de fazê-lo.
• Um recurso parametrizado, tickets://{ticket_id}, ao lado de um recurso fixo, tickets://open, mostrando ambos os estilos.
• Erros de validação levantados como ValueError simples, que o SDK transforma em uma resposta de erro estruturada em vez de travar o processo.
• Um modelo de prompt que referencia um ID de ticket, mantido intencionalmente simples, pois os prompts devem permanecer declarativos.

Mergulho Profundo

Como Funciona

• FastMCP("tickets-server") cria uma instância de servidor e imediatamente conecta as fases de conexão e negociação do ciclo de vida da requisição.
• Cada chamada @mcp.tool() registra a função decorada na tabela de ferramentas interna do servidor, com chave pelo nome da função, a menos que você passe um nome explícito.
• As dicas de tipo e a docstring da função são inspecionadas no momento do registro para construir o esquema JSON enviado aos clientes durante a negociação de capacidades.
• Quando um cliente chama uma ferramenta, o SDK valida os argumentos recebidos contra esse esquema antes que o corpo da sua função seja executado.
• Recursos seguem o mesmo padrão de registro, mas são endereçados por URI; um {placeholder} no modelo de URI se torna um parâmetro passado para sua função.

Tratamento de Erros

Levantar uma exceção Python padrão dentro de qualquer manipulador é a maneira correta de sinalizar falha.

@mcp.tool()
def get_priority_multiplier(priority: str) -> float:
    multipliers = {"low": 0.5, "normal": 1.0, "high": 2.0}
    if priority not in multipliers:
        raise ValueError(f"prioridade desconhecida '{priority}'")
    return multipliers[priority]

O SDK captura a exceção e a transforma em um resultado de erro estruturado que o cliente pode exibir ou raciocinar sobre, em vez de deixar que ela trave o processo do servidor.

Prefira levantar cedo com uma mensagem clara em vez de retornar uma string como "erro: entrada inválida", que o cliente trataria como um resultado bem-sucedido.

Ferramentas vs. Recursos vs. Prompts em Resumo

Notas Python

# Use dicas de tipo precisas, elas se tornam o esquema que o cliente valida.
@mcp.tool()
def set_priority(ticket_id: str, priority: str) -> str:
    ...
 
# Argumentos opcionais com padrões são refletidos como opcionais no esquema.
@mcp.tool()
def search_tickets(query: str, limit: int = 10) -> list[str]:
    ...

Dicas de tipo precisas importam mais aqui do que em código interno típico, pois se tornam parte de um contrato do qual um cliente depende, não apenas documentação para outro desenvolvedor.

Parâmetros e Valores de Retorno

Armadilhas

• Dicas de tipo vagas produzem um esquema inútil. Um parâmetro tipado como str onde na verdade é um conjunto fixo de valores (como priority) não dá ao cliente nenhuma dica sobre entradas válidas. Correção: valide contra um conjunto explícito dentro da função e levante um ValueError claro, ou use uma dica de tipo Literal onde o SDK a suporta.
• Retornar um erro em string em vez de levantar. Retornar "erro: não encontrado" de uma ferramenta parece um resultado bem-sucedido para o cliente. Correção: levante uma exceção; deixe o SDK convertê-la em uma resposta de erro adequada.
• Modificar estado compartilhado sem proteção para chamadas concorrentes. Um dicionário no nível do módulo como _tickets pode ser acessado por requisições sobrepostas se o servidor lidar com mais de uma sessão. Correção: use um banco de dados ou outro armazenamento seguro contra concorrência para o estado real assim que você passar da prototipagem local.
• Esquecer a docstring. Uma ferramenta sem docstring é registrada corretamente, mas não fornece nada para o Claude raciocinar ao decidir se deve chamá-la. Correção: sempre escreva uma docstring de uma linha descrevendo o que a ferramenta faz e quaisquer restrições em seus argumentos.
• Renomear os argumentos de uma ferramenta em uma versão posterior. Clientes existentes que chamam a ferramenta com os nomes de argumento antigos começarão a falhar na validação. Correção: trate os nomes dos argumentos como parte do seu contrato público e consulte estratégias de versionamento de esquema antes de alterá-los.
• Bloquear I/O dentro de um manipulador. Uma ferramenta que faz uma chamada de rede síncrona lenta prende o servidor para essa requisição. Correção: use async def para funções de ferramenta que realizam I/O; o SDK suporta manipuladores assíncronos diretamente.

Alternativas

FAQs

@mcp.tool()
def divide(a: float, b: float) -> float:
    if b == 0:
        raise ValueError("não é possível dividir por zero")
    return a / b

Relacionados

• Noções Básicas de Servidores MCP - o esqueleto mínimo no qual este artigo se baseia
• Como Servidores MCP Lidam com Requisições - o ciclo de vida no qual esses manipuladores se integram
• Construindo um Servidor MCP com o SDK TypeScript - os mesmos padrões em TypeScript
• Testando Servidores MCP Antes da Implantação - exercitando esses manipuladores com um cliente mock
• Referência de Versionamento e Limitação de Taxa de Esquemas de Ferramentas MCP - mantendo as alterações de ferramentas compatíveis com versões anteriores

Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e os atuais SDKs do Model Context Protocol Python/TypeScript. Nomes de modelos, versões de SDK e a especificação MCP mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs e modelcontextprotocol.io antes de confiar neles.