Tratamento de Erros

O MCP Server distingue dois tipos de erro, conforme a especificação do protocolo:

Protocol Errors

Erros de estrutura JSON-RPC, tratados automaticamente pelo SDK:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Unknown tool: invalid_tool_name"
    },
    "id": 1
}

Esses erros indicam problemas no formato da mensagem, não na lógica de negócio.

Tool Execution Errors

Erros de negócio retornados no resultado da tool com isError: true. O agente de IA recebe feedback acionável e pode se auto-corrigir:

{
    "content": [
        {
            "type": "text",
            "text": "{\"error\":true,\"type\":\"PermissionError\",\"message\":\"You do not have permission to perform this action\"}"
        }
    ],
    "isError": true
}

Tipos de erro de negócio

Tipo	Descrição	Ação esperada do agente
`PermissionError`	Sem permissão para a operação	Informar o usuário sobre a restrição
`NotFoundError`	Recurso não encontrado	Tentar com outro ID ou informar o usuário
`ConflictError`	Conflito (ex: duplicata)	Verificar dados e ajustar
`ValidationError`	Dados inválidos	Corrigir parâmetros e tentar novamente
`Error`	Erro interno genérico	Reportar erro ao usuário

Exemplos de cenários

Permissão negada

O usuário member tenta deletar um produto sem permissão products:delete:

Agente: Vou excluir o produto "Notebook Dell"
→ delete_product({ tenant_id: "...", id: "..." })
← PermissionError: You do not have permission to perform this action
Agente: Você não tem permissão para excluir produtos.
        Peça ao administrador para conceder essa permissão.

Recurso não encontrado

O agente tenta buscar um produto com ID inválido:

Agente: Buscando o produto...
→ get_product({ tenant_id: "...", id: "id-invalido" })
← NotFoundError: Product not found
Agente: Não encontrei um produto com esse ID.
        Pode verificar o ID correto?

Tenant inválido

O agente passa um tenant_id que o usuário não tem acesso:

→ list_products({ tenant_id: "tenant-sem-acesso" })
← Error: Membership not found or inactive
Agente: Não foi possível acessar essa empresa.
        Vamos verificar suas empresas disponíveis.
→ list_tenants()

Boas práticas para integradores

Sempre verifique isError: Se true, o conteúdo contém uma mensagem de erro, não dados
Use o campo type: Permite tratar cada tipo de erro de forma específica
Erros são acionáveis: O agente deve usar a mensagem para se auto-corrigir quando possível

Tratamento de Erros

Nesta página