Ferramentas, Recursos e Prompts no MCP
Nesta página
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):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.
Três capacidades, três intenções
Um servidor MCP pode expor três tipos de capacidades aos seus clientes. Estas não são intercambiáveis: cada uma responde a uma necessidade distinta, e confundir as três resulta em servidores difíceis de utilizar pelo modelo. Esta lição examina-as uma a uma, antes de abordar a questão que determina a qualidade do servidor: quantas ferramentas e com que granularidade.
Ferramentas: funções executáveis
As ferramentas são a capacidade mais utilizada do protocolo. Uma ferramenta é uma função que o modelo pode decidir invocar para realizar uma ação ou recuperar informação. A sua definição assenta em quatro elementos: um nome único e descritivo (create_issue, get_weather), uma descrição textual que indica ao modelo quando a deve chamar, um esquema JSON para os parâmetros de entrada com os seus tipos e restrições, e um formato de retorno — frequentemente texto ou JSON.
from mcp.server.mcpserver import MCPServer
app = MCPServer("My Server")
@app.tool()
def get_weather(latitude: float, longitude: float) -> str:
"""Retrieves current weather for the given coordinates.
Args:
latitude: Latitude in decimal degrees (-90 to 90)
longitude: Longitude in decimal degrees (-180 to 180)
Returns:
Text description of current weather
"""
# Weather API call logic
return f"Sunny, 22°C at ({latitude}, {longitude})"
Não subestime a descrição e a tipagem: o modelo não vê mais nada. Não tem acesso ao seu código, não consegue adivinhar as suas intenções e não pode testar uma chamada para ver o que acontece. Descrições vagas ou parâmetros mal tipados produzem mecanicamente chamadas incorretas.
Alguns hábitos tornam as suas ferramentas significativamente mais fiáveis. Dê-lhes nomes que descrevam a ação — book_restaurant diz tudo, process_request não diz nada — e descreva tanto a ação como o conteúdo do retorno, já que o modelo deve antecipar o que vai recuperar. Anote sempre os parâmetros em Python e escreva docstrings estruturadas com Args e Returns: estes alimentam o esquema que o modelo vê. Por fim, devolva valores legíveis em vez de identificadores opacos; uma ferramenta que devolve "John Smith" permite ao modelo compor uma frase, enquanto uma que devolve um UUID obriga-o a adivinhar.
Recursos: dados legíveis
Os recursos expõem dados que o cliente pode ler sem efeitos colaterais. A nuance em relação às ferramentas resume-se a um verbo: uma ferramenta faz algo, um recurso contém algo. O conteúdo de um ficheiro de configuração, uma base de conhecimento, documentação de API ou o estado atual de um sistema são todos recursos naturais.
@app.resource("config://database")
def get_db_config() -> str:
"""Current database configuration."""
return json.dumps({
"host": "localhost",
"port": 5432,
"database": "production"
})
Cada recurso é identificado por um URI — config://database, file:///path/to/doc — que o cliente pode listar e depois ler sob demanda. Na prática, são menos utilizados do que as ferramentas, uma vez que uma simples ferramenta que devolve dados cobre a maioria das necessidades. Mantêm-se úteis quando pretende publicar dados estáticos ou semiestáticos sem lógica de execução associada.
Prompts: modelos reutilizáveis
Os Prompts do MCP são modelos parametrizáveis que o servidor disponibiliza. Servem para partilhar instruções testadas para uma determinada tarefa, em vez de deixar que cada um reinvente a sua formulação.
@app.prompt()
def code_review(language: str, code: str) -> str:
"""Generates a code review prompt for the given language."""
return f"""You are an expert in {language}.
Analyze the following code and identify:
1. Potential bugs
2. Performance issues
3. Readability improvements
Code to analyze:
```{language}
{code}
```"""
Esta utilização faz mais sentido num contexto de equipa. Um programador sénior codifica os seus prompts de revisão de código, depuração ou análise de arquitetura num servidor MCP, e toda a equipa acede aos mesmos a partir do seu próprio cliente, com a mesma qualidade de instrução.
Negociação de capacidades
Quando um cliente se liga a um servidor, ocorre uma fase de negociação antes de qualquer utilização:
- O cliente solicita as capacidades do servidor
- O servidor responde com a sua lista de ferramentas, recursos e prompts
- O cliente apresenta estas capacidades ao modelo de linguagem
- O modelo utiliza as descrições para decidir o que invocar
Esta negociação é dinâmica, o que constitui uma propriedade explorável: o mesmo servidor pode anunciar capacidades diferentes consoante o utilizador ligado ou o contexto da chamada — uma conta de administrador vê ferramentas que uma conta de só-leitura nunca verá.
Quantas ferramentas por servidor?
A questão parece trivial, mas condiciona a taxa de erro do seu agente. Mantenha os seus servidores focados: três a dez ferramentas bem definidas funcionam melhor do que cinquenta genéricas. Além de certo volume, o modelo dispersa as suas escolhas e acaba por chamar a ferramenta errada ou empilhar chamadas desnecessárias.
Se o seu âmbito funcional for amplo, divida-o em vários servidores especializados — um para operações Git, outro para gestão de projetos, outro para monitorização. O cliente sabe ligar-se a vários servidores simultaneamente e ativar apenas os necessários para a tarefa atual, o que equivale a carregar o contexto útil em vez de todo o catálogo.
Uma última compensação merece a sua atenção: a granularidade. Expor três ferramentas para listar restaurantes, verificar disponibilidade e depois reservar obriga o modelo a orquestrar uma sequência, com risco de erro a cada passo. Uma única ferramenta de fluxo de trabalho — book_restaurant — encapsula a sequência completa, reduz o número de idas e voltas e move a lógica de negócio para onde é testável: no seu código.
Pontos-chave
- Ferramentas = ações executáveis (90% dos casos de uso), exigem descrição e tipagem precisas
- Recursos = dados legíveis via URI, sem efeitos colaterais
- Prompts = modelos reutilizáveis, úteis para equipas
- Mantenha os seus servidores focados (máximo de 3–10 ferramentas)
- Prefira ferramentas de fluxo de trabalho a ferramentas excessivamente granulares
- A qualidade da descrição determina a eficiência do modelo