MCP para ERP: um guia prático

Comece pela transação, não pela tabela

O primeiro instinto ao expor um ERP é gerar uma ferramenta por tabela com criar, ler, atualizar e eliminar em cada uma. Isso produz uma lista grande e uniforme que um modelo gere mal, porque a regra de negócio de que uma fatura precisa de uma taxa de imposto em cada linha, ou que o stock não pode ser enviado antes de ser reservado, não está em lugar algum que o modelo possa ver. Exponha as ações em vez disso. Um teste útil é se uma pessoa poderia descrever a ferramenta como algo que fez hoje: levantou uma fatura, registou um pagamento, moveu um negócio, adiou uma cobrança. Cada uma dessas ações tem as suas regras, valida as suas entradas e retorna um resultado legível.

Junto às ações, adicione um pequeno número de ferramentas de resumo que respondam às perguntas que um modelo faz antes de agir. Uma chamada que retorna o perfil de uma conta, saúde, itens abertos e histórico recente poupa ao modelo quatro chamadas e vários milhares de tokens de contexto, e torna a próxima ação melhor informada. O Sois chama a estas ferramentas de examinador; examinarContacto e obterResumoContabilístico são dois. Mantenha também a superfície total em vista: o Claude Code limita a saída de um servidor por chamada por defeito, e tanto o Claude como o OpenAI oferecem carregamento diferido ou pesquisa de ferramentas para listas grandes, portanto, um servidor com várias centenas de ferramentas deve devolvê-las numa ordem determinística (a especificação pede isso para que os clientes possam armazenar em cache) e deve filtrar por função antes de listar.

Nomeie ferramentas para que um modelo escolha a correta

A especificação limita os nomes de forma leve: um até 128 caracteres, letras, dígitos, sublinhado, hífen e ponto, sensível a maiúsculas e minúsculas, único dentro do servidor. Tudo o resto é convenção, e a convenção que funciona é um verbo seguido do substantivo de negócio num caso consistente, com os mesmos verbos a significar as mesmas coisas em todo o lado. Um modelo a escolher entre procurarFaturas, obterFactura e criar fatura está a escolher entre uma lista, um registo e uma escrita, e aprende esse padrão uma vez para todo o servidor.

As descrições são lidas por um modelo sob pressão para agir, por isso escreva-as como instruções. Declare o que a ferramenta faz na primeira frase, depois as condições. Se uma ferramenta irmã for a escolha certa para um pedido próximo, diga-o pelo nome. Se um campo tiver de ser definido para que o resultado seja correto, diga isso em MAIÚSCULAS se necessário; a ferramenta de fatura da Sois diz ao modelo que a taxa de imposto deve ser definida em cada linha e que as taxas exatas vêm de listarTiposDeImposto, because an invoice with no VAT is a worse failure than a refused call. Include one example call. Everything the model needs to call the tool correctly should be in the tool, because it will never open your documentation.

Uma definição de ferramenta de exemplo

Esta é uma ferramenta de fatura da Sois como um cliente a recebe de tools/list, reduzido aos campos que importam, com anotações e um esquema de saída adicionados na forma que a especificação atual define. Mostra o padrão: um nome verbo-substantivo, uma descrição instrucional, um esquema cujas descrições de propriedades fazem a prevenção de erros do modelo, e dicas que um cliente pode usar para decidir se deve confirmar.

{
  "name": "createInvoice",
  "title": "Create invoice",
  "description": "Create a new invoice of any type and return the draft with its auto-generated number. TAX: set tax_rate on each line (for example 20 for 20% VAT); call listTaxTypes for this workspace's exact rates. If the user says 'plus VAT' you MUST set tax_rate or the invoice goes out with no VAT. To email the result use sendInvoice. Example: createInvoice({ type: \"sales_invoice\", contact_id: \"uuid\", currency: \"GBP\", lines: [{ description: \"Consulting\", quantity: 10, unit_price: 150 }] })",
  "inputSchema": {
    "type": "object",
    "properties": {
      "type": { "type": "string", "description": "sales_invoice, purchase_invoice, sales_credit_note or purchase_credit_note" },
      "contact_id": { "type": "string", "description": "Contact UUID (bill-to for sales, bill-from for purchases)" },
      "currency": { "type": "string", "description": "ISO code, for example GBP. Uses the workspace default if omitted" },
      "invoice_date": { "type": "string", "description": "ISO date. Defaults to today" },
      "reference": { "type": "string" },
      "lines": {
        "type": "array",
        "description": "Line items. Every line MUST carry the numeric unit_price the user asked for",
        "items": {
          "type": "object",
          "properties": {
            "description": { "type": "string" },
            "quantity": { "type": "number", "description": "Defaults to 1" },
            "unit_price": { "type": "number", "description": "NUMBER only: no currency symbols, no thousands separators. Use the exact amount stated; never guess or round" },
            "tax_rate": { "type": "number" },
            "discount_percent": { "type": "number" }
          },
          "required": ["description", "unit_price"]
        }
      }
    },
    "required": ["type"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "invoice_id": { "type": "string" },
      "number": { "type": "string" },
      "status": { "type": "string" },
      "total": { "type": "number" }
    },
    "required": ["invoice_id", "number", "status"]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  }
}

As anotações dizem: isto escreve, apenas adiciona (um rascunho), chamá-lo duas vezes cria dois rascunhos, e não toca em nada fora do sistema. Os clientes devem tratar as anotações como não confiáveis, a menos que o servidor seja confiável, portanto, são dicas para o comportamento de confirmação, não um substituto para as próprias verificações do servidor.

Três escolhas nessa definição são deliberadas. O resultado devolve um identificador que o modelo deve transportar para dentro de enviar fatura e registarPagamento, que é a forma recomendada pela especificação para relacionar chamadas agora que os servidores não mantêm estado de sessão. A ferramenta cria um rascunho, não uma fatura publicada, portanto a escrita é aditiva e uma pessoa ou uma ferramenta de aprovação separada finaliza-o. E o esquema de saída significa que uma integração pode ler o número e o total como dados, enquanto o modelo lê o mesmo resultado como texto.

Delimitar ferramentas ao utilizador

Através do HTTP, o chamador chega com um token de acesso OAuth vinculado ao seu servidor, e esse token identifica uma pessoa. A especificação permite que o resultado de tools/list variar consoante as credenciais na solicitação, portanto, a primeira decisão de escopo é filtrar a lista pelo papel dessa pessoa antes de a devolver: um utilizador de armazém não recebe aprovar faturaA lista não deve variar por ligação ou como um efeito colateral de outras chamadas, apenas por autorização, que é o que a torna cacheável.

A segunda decisão é verificar novamente na execução. Um cliente pode enviar qualquer chamada que desejar, e um modelo pode ser manipulado por texto num resultado de ferramenta para tentar um. Resolva o utilizador a partir do token em cada chamada, verifique a permissão que a ferramenta requer e recuse com um erro de execução da ferramenta que o modelo pode ler. Mantenha os scopes OAuth amplos (Sois emite scopes de leitura, escrita e offline) e deixe os próprios papéis do ERP serem a fronteira detalhada, porque esses papéis já existem, já são mantidos e já significam algo para o negócio. Atribua cada chamada à pessoa no registo com os seus argumentos e resultado, para que o trabalho de um agente seja revisável exatamente como o de uma pessoa.

1. O token chegaValide a assinatura e que o público é este servidor, conforme exige a RFC 8707; rejeite qualquer outra coisa com 401.
2. Resolva a pessoaMapeie o token a um utilizador no espaço de trabalho e carregue o seu papel e aplicações instaladas.
3. Filtre a listaRetorne apenas as ferramentas que esse papel pode usar, numa ordem estável, a partir de tools/list.
4. Verifique a chamadaEm tools/call, verifique novamente a permissão e recuse com isError se estiver em falta; nada será executado.
5. Execute e registeExecute a transação, meça-a se o seu próprio agente fez o raciocínio, e escreva a chamada no registo de auditoria sob essa pessoa.

Gerir gravações

Um modelo que recebe um resultado ambíguo chamará novamente, e um que recebe um erro tentará uma entrada corrigida. Projete para isso. As operações que criam devem retornar um identificador e, sempre que possível, aceitar uma chave de idempotência ou uma chave natural para que uma repetição seja detetada. As operações que alteram o estado devem ser explícitas sobre a transição que realizam e recusar aquelas impossíveis com uma razão legível: registar um pagamento contra uma fatura anulada é um isError resultado a dizer isso, não um não-operacional silencioso e não um rastreio de pilha. Nunca deixe uma escrita parcial; se uma ferramenta de múltiplos passos não puder ser concluída, reverta e reporte.

• Prefira rascunhos e aprovações. Faça com que a criação seja aditiva (um rascunho) e dê à finalização a sua própria ferramenta com a sua própria permissão, de modo que o passo destrutivo seja aquele que um cliente confirma e um papel controla.
• Marque ferramentas destrutivas. Definir dica destrutiva sobre anulações e eliminações e diga-o na descrição; Claude e ChatGPT usam tais sinais ao decidir perguntar antes de chamar.
• Pergunte em vez de adivinhar. Quando uma chamada precisa de uma decisão que a ferramenta não pode tomar, devolva um resultado que requer entrada com um pedido de elicitação; o cliente coloca a questão à pessoa e tenta novamente a chamada com a resposta.
• Limite o raio de impacto. Limite a taxa por conexão, limite o gasto por integração onde o seu próprio agente faz raciocínio, e valide cada entrada no servidor, independentemente do esquema, porque o esquema é um conselho para o modelo, não uma imposição.

Testar a superfície com um cliente real

O inspetor MCP irá exercer tools/list e tools/call e percorrer o fluxo OAuth. O verdadeiro teste é um modelo. Conecte Claude como um conector personalizado, ou ChatGPT em modo de desenvolvedor, faça login como um utilizador com um papel restrito e peça um resultado rotineiro que necessite de três ou quatro ferramentas. Observe quais ferramentas ele escolhe e porquê; uma escolha errada é quase sempre um problema de descrição. Depois, faça login como um utilizador sem uma das permissões e confirme que a execução para na chamada certa com uma razão que o modelo repete.

É assim que o servidor de espaço de trabalho Sois é construído e verificado: transações como ferramentas, descrições instrucionais, uma lista filtrada por papel, uma segunda verificação em cada chamada, rascunhos antes das aprovações, e um registo que uma pessoa pode ler. Os desenvolvedores que constroem aplicações para o mercado publicam ferramentas na mesma lista sob as mesmas regras, de modo que uma aplicação é operável por qualquer agente no momento em que é instalada. O padrão não é específico de um produto; qualquer ERP que o adote torna-se algo que um agente pode executar.

Perguntas que as pessoas fazem

Este artigo é revisto quando os produtos que descreve mudam. Próxima revisão agendada: 4 de dezembro de 2026.