Definindo Ferramentas Chamáveis em um Servidor MCP

Uma ferramenta chamável é a maneira mais direta pela qual um servidor MCP dá ao modelo algo a fazer.

Acertar uma ferramenta significa que o modelo pode encontrá-la, entender o que ela faz, chamá-la com argumentos válidos e dar sentido ao que retorna.

Resumo

Uma ferramenta no SDK Python do MCP começa como uma função comum decorada com @mcp.tool().

O nome da função, seus parâmetros com dicas de tipo e sua docstring juntos se tornam o esquema que um cliente usa para decidir quando e como chamá-la.

Os manipuladores devem permanecer estreitos e previsíveis, fazendo um trabalho bem feito em vez de ramificar em vários comportamentos não relacionados com base em um argumento de flag.

Erros devem ser levantados como exceções com uma mensagem clara, não engolidos ou retornados como strings ambíguas, para que o modelo receba feedback útil quando uma chamada falhar.

Entradas estruturadas e validadas (via modelos Pydantic ou dicas de tipo simples) capturam argumentos ruins antes que o código do seu manipulador seja executado.

Receita

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("tool-recipes")
 
@mcp.tool()
def get_weather(city: str, units: str = "celsius") -> str:
    """Get the current weather for a city.
 
    Args:
        city: The city name, e.g. "Austin" or "Tokyo".
        units: Either "celsius" or "fahrenheit". Defaults to "celsius".
    """
    if units not in ("celsius", "fahrenheit"):
        raise ValueError('units must be "celsius" or "fahrenheit"')
    return f"72 degrees {units} and sunny in {city}"

Quando usar isso:

• O modelo precisa executar uma ação ou computação, não apenas ler dados estáticos.
• A operação tem um conjunto pequeno e bem tipado de entradas que se mapeiam claramente para parâmetros de função.
• Você deseja que a mesma capacidade seja acessível a partir do Claude Code, Claude Desktop ou um aplicativo SDK de Agente personalizado sem reescrevê-la por cliente.
• O resultado da chamada deve se tornar parte da conversa, não apenas ser armazenado em cache ou exibido separadamente.

Exemplo de Trabalho

# server.py
from typing import Literal
 
from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field
 
mcp = FastMCP("task-tools")
 
# In-memory store for this example; swap for a real database in production.
_tasks: dict[int, dict] = {}
_next_id = 1
 
 
class CreateTaskInput(BaseModel):
    title: str = Field(..., min_length=1, max_length=200, description="Short task title")
    priority: Literal["low", "medium", "high"] = Field(
        "medium", description="Task priority level"
    )
 
 
@mcp.tool()
def create_task(input: CreateTaskInput) -> str:
    """Create a new task and return its id.
 
    Use this when the user asks to add, track, or remember a to-do item.
    """
    global _next_id
    task_id = _next_id
    _next_id += 1
    _tasks[task_id] = {"title": input.title, "priority": input.priority, "done": False}
    return f"Created task {task_id}: {input.title} (priority: {input.priority})"
 
 
@mcp.tool()
def complete_task(task_id: int) -> str:
    """Mark an existing task as done.
 
    Args:
        task_id: The numeric id returned by create_task.
    """
    task = _tasks.get(task_id)
    if task is None:
        raise ValueError(f"No task found with id {task_id}")
    task["done"] = True
    return f"Task {task_id} ({task['title']}) marked done"
 
 
@mcp.tool()
def list_tasks(only_open: bool = True) -> str:
    """List tracked tasks.
 
    Args:
        only_open: If True, hide tasks already marked done. Defaults to True.
    """
    rows = [
        f"#{tid} [{t['priority']}] {t['title']}{' (done)' if t['done'] else ''}"
        for tid, t in _tasks.items()
        if not (only_open and t["done"])
    ]
    return "\n".join(rows) if rows else "No tasks found."
 
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

O que isso demonstra:

• Três ferramentas estreitas e de propósito único (create_task, complete_task, list_tasks) em vez de uma ferramenta com um flag mode.
• Um modelo Pydantic (CreateTaskInput) validando uma entrada estruturada com uma restrição de comprimento e um conjunto restrito de valores permitidos.
• Um tipo Literal restringindo priority a exatamente três strings válidas, aplicadas antes que o corpo do manipulador seja executado.
• Tratamento de erros consistente: IDs desconhecidos levantam ValueError com uma mensagem nomeando o problema específico.
• Retornos de string simples que leem naturalmente quando o modelo os exibe em uma conversa.

Mergulho Profundo

Como Funciona

• Quando o servidor inicia, FastMCP inspeciona cada função decorada com @mcp.tool() e constrói um Esquema JSON a partir de suas dicas de tipo e valores padrão.
• A docstring da função se torna a descrição da ferramenta que o cliente usa para decidir quando a ferramenta é relevante.
• Quando um cliente chama list_tools(), ele recebe este esquema e descrição para cada ferramenta registrada, sem que você precise escrever nenhum esquema manualmente.
• Quando o modelo decide chamar uma ferramenta, o cliente envia o nome da ferramenta mais um objeto JSON de argumentos; o SDK valida esse objeto contra o esquema gerado antes de invocar sua função.
• Se a validação falhar (tipo incorreto, campo obrigatório ausente, valor fora de um conjunto Literal), o SDK retorna um erro de esquema para o cliente sem nunca chamar seu manipulador.

Regras de Nomeação e Descrição em Resumo

Notas de Python

# Prefer a constrained type over a loose string when the valid set is small and known.
from typing import Literal
 
@mcp.tool()
def set_status(status: Literal["open", "in_progress", "closed"]) -> str:
    """Set the status of the current item."""
    return f"Status set to {status}"
 
# For richer validation (ranges, formats, nested fields), use a Pydantic model
# as the single parameter, as shown in CreateTaskInput above.

Parâmetros e Valores de Retorno

Armadilhas

• Nomes de ferramentas vagos como handle ou process. O modelo não tem nada para associar a intenção. Correção: use um nome específico, começando com verbo, como create_task ou send_email.
• Uma ferramenta com um parâmetro de string mode ou action que ramifica em comportamentos não relacionados. Isso confunde a descoberta baseada em esquema e aumenta a chance de uma chamada incorreta. Correção: divida-a em ferramentas separadas e de escopo restrito.
• Retornar None ou uma string vazia em caso de falha em vez de levantar uma exceção. O modelo não tem sinal de que algo deu errado e pode relatar sucesso incorretamente. Correção: levante uma exceção com uma mensagem específica; deixe o SDK traduzi-la em um erro de ferramenta.
• Docstrings ausentes ou superficiais. Sem uma descrição, o modelo está adivinhando o que uma ferramenta faz apenas pelo seu nome. Correção: sempre inclua um resumo de uma linha mais um bloco Args:.
• Ignorar a validação de entrada em intervalos numéricos ou de string. Um manipulador que confia cegamente em suas entradas pode falhar em casos extremos como contagens negativas ou strings vazias. Correção: use Literal, restrições Field do Pydantic ou verificações explícitas no início do manipulador.
• Mutar estado global compartilhado sem nenhuma proteção. Duas chamadas rápidas de ferramentas contra o mesmo armazenamento em memória podem competir ou corromper dados. Correção: use um armazenamento de dados real com transações, ou adicione bloqueio, quando você sair de uma demonstração.

Alternativas

FAQs

@mcp.tool()
def withdraw(account_id: str, amount: float) -> str:
    """Withdraw funds from an account."""
    if amount <= 0:
        raise ValueError("amount must be positive")
    return f"Withdrew {amount} from {account_id}"

Relacionado

• Entendendo MCP: Ferramentas, Recursos e Prompts - a base conceitual do que é uma ferramenta versus um recurso ou prompt.
• Noções Básicas de Conceitos Principais do MCP - um servidor e cliente de ferramenta única mínima para construir.
• Expondo Dados Legíveis como Recursos MCP - o primitivo irmão para dados somente leitura.
• Comparação de Ferramentas MCP vs. Recursos vs. Prompts - decidindo quando uma capacidade pertence a uma ferramenta.
• Melhores Práticas de Conceitos Principais do MCP - uma lista de verificação para qualidade de esquema e nomenclatura.

Versões da 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 a especificação atual do Model Context Protocol. 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.