Documentação Oficial do MCP em Português
  1. Conceitos
Documentação Oficial do MCP em Português
  • Get Started
    • Introdução
    • Servidores de exemplo
    • Clientes de exemplo
    • Início rápido
      • Para os desenvolvedores de servidores
      • Para os desenvolvedores de clientes
      • Para utilizadores do Claude Desktop
  • Tutoriais
    • Construção de MCP com LLMs
    • Depuração
    • Inspetor
  • Conceitos
    • Arquitetura central
    • Recursos
    • Avisos
    • Ferramentas
    • Amostragem
    • Raízes
    • Transportes
  • Desenvolvimento
    • O que há de novo
    • Roteiro
    • Contribuindo
  1. Conceitos

Ferramentas

Habilitar LLMs para executar ações através do seu servidor
As Tools são um primitivo poderoso no Model Context Protocol (MCP) que permite que os servidores exponham funcionalidades executáveis aos clientes. Através das Tools, os LLMs podem interagir com sistemas externos, realizar cálculos e tomar ações no mundo real.
As Tools são projetadas para serem controladas por modelo, o que significa que as Tools são expostas dos servidores para os clientes com a intenção de que o modelo de IA seja capaz de invocá-las automaticamente (com um humano no circuito para conceder aprovação).

Visão geral#

As Tools no MCP permitem que os servidores exponham funções executáveis que podem ser invocadas por clientes e usadas por LLMs para realizar ações. Os principais aspectos das Tools incluem:
Descoberta: Os clientes podem listar as Tools disponíveis através do endpoint tools/list
Invocação: As Tools são chamadas usando o endpoint tools/call, onde os servidores realizam a operação solicitada e retornam os resultados
Flexibilidade: As Tools podem variar de cálculos simples a interações complexas de API
Como os recursos, as Tools são identificadas por nomes exclusivos e podem incluir descrições para orientar seu uso. No entanto, ao contrário dos recursos, as Tools representam operações dinâmicas que podem modificar o estado ou interagir com sistemas externos.

Estrutura de definição de Tool#

Cada Tool é definida com a seguinte estrutura:

Implementando Tools#

Aqui está um exemplo de implementação de uma Tool básica em um servidor MCP:
TypeScript
Python

Padrões de Tool de exemplo#

Aqui estão alguns exemplos de tipos de Tools que um servidor poderia fornecer:

Operações de sistema#

Tools que interagem com o sistema local:

Integrações de API#

Tools que envolvem APIs externas:

Processamento de dados#

Tools que transformam ou analisam dados:

Melhores práticas#

Ao implementar Tools:
1.
Forneça nomes e descrições claras e descritivas
2.
Use definições detalhadas de JSON Schema para parâmetros
3.
Inclua exemplos nas descrições das Tools para demonstrar como o modelo deve usá-las
4.
Implemente tratamento e validação de erros adequados
5.
Use relatórios de progresso para operações longas
6.
Mantenha as operações das Tools focadas e atômicas
7.
Documente as estruturas de valor de retorno esperadas
8.
Implemente timeouts adequados
9.
Considere a limitação de taxa para operações com uso intensivo de recursos
10.
Registre o uso da Tool para depuração e monitoramento

Considerações de segurança#

Ao expor Tools:

Validação de entrada#

Valide todos os parâmetros em relação ao schema
Higienize caminhos de arquivos e comandos do sistema
Valide URLs e identificadores externos
Verifique os tamanhos e intervalos dos parâmetros
Evite a injeção de comandos

Controle de acesso#

Implemente a autenticação onde for necessário
Use verificações de autorização apropriadas
Audite o uso da Tool
Limite a taxa de solicitações
Monitore para evitar abusos

Tratamento de erros#

Não exponha erros internos aos clientes
Registre erros relevantes para a segurança
Lide com os timeouts de forma adequada
Limpe os recursos após os erros
Valide os valores de retorno

Descoberta e atualizações de Tool#

O MCP suporta a descoberta dinâmica de Tools:
1.
Os clientes podem listar as Tools disponíveis a qualquer momento
2.
Os servidores podem notificar os clientes quando as Tools mudarem usando notifications/tools/list_changed
3.
As Tools podem ser adicionadas ou removidas durante o tempo de execução
4.
As definições de Tool podem ser atualizadas (embora isso deva ser feito com cuidado)

Tratamento de erros#

Os erros de Tool devem ser relatados dentro do objeto de resultado, não como erros de nível de protocolo MCP. Isso permite que o LLM veja e potencialmente lide com o erro. Quando uma Tool encontra um erro:
1.
Defina isError como true no resultado
2.
Inclua detalhes do erro no array content
Aqui está um exemplo de tratamento de erros adequado para Tools:
TypeScript
Python
Essa abordagem permite que o LLM veja que ocorreu um erro e, potencialmente, tome medidas corretivas ou solicite intervenção humana.

Testando Tools#

Uma estratégia de teste abrangente para Tools MCP deve cobrir:
Teste funcional: Verifique se as Tools são executadas corretamente com entradas válidas e lidam com entradas inválidas de forma apropriada
Teste de integração: Teste a interação da Tool com sistemas externos usando dependências reais e simuladas
Teste de segurança: Valide a autenticação, autorização, higienização de entrada e limitação de taxa
Teste de desempenho: Verifique o comportamento sob carga, tratamento de timeout e limpeza de recursos
Tratamento de erros: Garanta que as Tools relatem erros adequadamente através do protocolo MCP e limpem os recursos
Modified at 2025-03-12 10:12:21
Previous
Avisos
Next
Amostragem
Built with