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

Ferramentas, Recursos e Prompts no MCP

Aula 3 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Três capacidades, três intenções
  2. Ferramentas: funções executáveis
  3. Recursos: dados legíveis
  4. Prompts: modelos reutilizáveis
  5. Negociação de capacidades
  6. Quantas ferramentas por servidor?
  7. Pontos-chave

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

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:

  1. O cliente solicita as capacidades do servidor
  2. O servidor responde com a sua lista de ferramentas, recursos e prompts
  3. O cliente apresenta estas capacidades ao modelo de linguagem
  4. 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