Integrar com IA (MCP)

O MCP (Model Context Protocol) permite que um assistente consulte a documentação oficial e use ferramentas do Minstrel durante o desenvolvimento. Você pode começar sem conta e conectar seu sandbox quando precisar testar a integração.

Escolha sua conexão

O transporte é Streamable HTTP, usando uma única URL por conexão. A versão autenticada aceita Authorization: Bearer SUA_CHAVE em clientes que permitem configurar headers. Ela usa chaves de API, sem fluxo de autorização OAuth.

Configure seu assistente

Escolha a conexão e o cliente para copiar a configuração. O endereço abaixo acompanha o ambiente desta documentação.

{
  "servers": {
    "minstrel-docs": {
      "type": "http",
      "url": "https://api.minstrel.com.br/v1/mcp/docs"
    }
  }
}

As opções Claude Code e Claude web/Desktop têm configurações próprias, além das opções para VS Code e Cursor. No Claude Code, salve o JSON em .mcp.json na raiz do projeto e abra /mcp para aprovar a conexão.

No VS Code, habilite as ferramentas MCP no chat do agente após salvar o arquivo. No Cursor, adicione a configuração no arquivo pessoal indicado e habilite o servidor em suas configurações MCP. Use um cliente compatível com Streamable HTTP e com o mecanismo de credenciais do exemplo escolhido.

Para a versão autenticada, abra Configurações → Chaves de API no painel e crie uma chave no ambiente desejado. Use a opção MCP de leitura ou, para desenvolver com ações de teste, MCP com testes no sandbox. Essas opções preenchem os escopos, validade de 30 dias e limite de 120 requisições por minuto; revise os dados antes de criar. O segredo aparece uma única vez e a chave pode ser revogada nessa mesma aba. Em produção, o MCP oferece somente consultas.

O bloco Comece aqui da visão geral reúne o checklist de configuração e os atalhos para este guia e para Primeiros passos.

Não cole a chave em mensagens do assistente. No VS Code, informe-a na entrada protegida; no exemplo do Cursor, substitua o marcador somente no seu arquivo pessoal, fora do repositório. A configuração copiada pelo Minstrel nunca contém o segredo.

Claude Code

Escolha Claude Code no configurador acima. Para a documentação pública, basta salvar o JSON e habilitar o servidor em /mcp. O Claude Code pode acessar a API local em localhost durante o desenvolvimento.

Para conectar sua conta, o JSON referencia ${MINSTREL_API_KEY}. Defina essa variável no terminal antes de abrir o Claude Code. O arquivo .env sozinho não exporta a variável para o processo do Claude.

No PowerShell, leia a chave sem gravá-la no histórico:

$minstrelCredential = Read-Host 'Chave MCP Minstrel' -AsSecureString
$env:MINSTREL_API_KEY = [System.Net.NetworkCredential]::new('', $minstrelCredential).Password
claude
Remove-Item Env:MINSTREL_API_KEY

No Bash:

read -rsp 'Chave MCP Minstrel: ' MINSTREL_API_KEY
export MINSTREL_API_KEY
claude
unset MINSTREL_API_KEY

Em /mcp, confira o servidor minstrel-docs ou minstrel-account. Mantenha a aprovação das ferramentas de escrita. A chave e as permissões são as mesmas usadas pelos outros clientes. Veja a configuração oficial do Claude Code.

Claude web e Desktop

Escolha Claude web/Desktop no configurador e siga as instruções copiadas. Esse caminho usa um conector remoto da conta Claude, com URL HTTPS pública. A conexão sai dos servidores da Anthropic: uma URL localhost não funciona nesse modo, mesmo quando o aplicativo Desktop está no seu computador.

1. No Claude, abra Personalizar (Customize) → Conectores (Connectors) e adicione um conector personalizado. Em contas de equipe, o responsável pode precisar adicionar o conector nas configurações da organização.
2. Informe o nome e a URL pública mostrados no configurador.
3. Em Authentication, escolha No sign in, pois o Minstrel usa chave de API em vez de login OAuth.
4. Para a documentação pública, não adicione headers. Para sua conta, em Request headers, adicione Authorization com o valor Bearer SUA_CHAVE. Informe a chave somente nesse campo, sem colá-la em uma conversa.
5. Salve o conector e habilite-o na conversa do Claude.

Em equipes, uma chave fixa concede suas permissões a quem utiliza o conector. Use uma chave dedicada e disponibilize-a apenas às pessoas autorizadas. Confira os passos na documentação oficial dos conectores Claude.

Peça sua primeira integração

Comece com uma solicitação como esta:

Consulte os guias oficiais do Minstrel pelo MCP. Implemente uma cobrança Pix
no meu projeto e um endpoint para receber payment.captured.
Use centavos inteiros, chave de idempotência e validação da assinatura do webhook
sobre o corpo bruto. Primeiro explique as alterações e faça os testes no sandbox.

O prompt MCP integrate_minstrel também reúne os guias conforme seu objetivo: checkout, Pix, boleto, assinaturas ou webhooks. A documentação informa como implementar o fluxo; seu assistente ainda precisa editar e testar o seu projeto.

Ferramentas de documentação

Estas ferramentas estão disponíveis nas duas conexões:

O servidor também publica os guias, o OpenAPI e o catálogo de eventos como resources MCP. O conteúdo é gerado a partir dos mesmos arquivos desta documentação durante o build da API.

Ferramentas da conta

Além de mcp:read, a chave precisa dos escopos indicados. A lista de ferramentas que seu assistente recebe já considera essas permissões e o ambiente da chave.

As ferramentas de criação, simulação, teste e reenvio exigem uma chave de sandbox, confirm: true e uma idempotencyKey de 8 a 128 caracteres. Use a mesma chave para repetir uma operação e uma nova chave para uma operação nova. O cliente deve manter a confirmação humana de execução das ferramentas.

Em produção, o MCP desta versão oferece apenas consultas, mesmo que a chave tenha escopos de escrita. Não há ferramentas de cobrança, captura, estorno ou alteração de credenciais em produção.

Teste pagamentos e webhooks

1. No painel, selecione Sandbox e conecte o plugin Minstrel Sandbox.
2. Em Configurações → Chaves de API, crie uma chave de sandbox usando MCP com testes no sandbox.
3. Use get_account_context para confirmar o ambiente retornado pela chave.
4. Cadastre um cliente com create_sandbox_customer, usando um externalId estável.
5. Crie a cobrança com create_sandbox_payment. Para Pix e boleto, use simulate_sandbox_payment para simular a confirmação ou a expiração.
6. Cadastre a URL do seu receptor com create_sandbox_webhook e selecione os eventos.
7. Abra Webhooks no painel para obter o segredo de assinatura e configurá-lo diretamente no servidor receptor. O MCP não retorna esse segredo ao assistente.
8. Use test_sandbox_webhook, consulte as entregas e confira a resposta do seu receptor.

O receptor deve validar a assinatura HMAC com o corpo bruto, conferir a tolerância do timestamp, deduplicar pelo ID do evento e processar em uma fila. Confira o formato e o exemplo completo em Webhooks.

O MCP chama os mesmos serviços de pagamento, idempotência e entrega da API. Os testes de sandbox não consomem as 50 transações de produção do período gratuito.

Dados e permissões

A organização e o ambiente vêm da credencial; a ferramenta não aceita parâmetros para acessar outra conta ou trocar para produção. Trocar o seletor do painel também não muda o ambiente de uma chave que já foi criada.

Consultas autenticadas podem devolver dados de clientes e pagamentos. Habilite somente os escopos necessários e avalie o tratamento de dados pelo provedor do assistente escolhido. Tokens de cartão e segredos não devem entrar no chat; número de cartão e CVV são recusados pela API.

As execuções autenticadas ficam na auditoria com ferramenta, ambiente, chave e resultado. Os argumentos e o conteúdo retornado não são gravados nessa auditoria.

Resolver problemas

Para respostas de negócio e validação, confira isError e o código retornado pela ferramenta. Nenhum desses erros autoriza trocar de conta, ambiente ou repetir uma cobrança com outra chave de idempotência.