Suporte

Canal de atendimento

O suporte para o MCP é feito por e-mail, pelo canal de implantações: implantacaoempresas@btgpactual.com.

Para agilizar o diagnóstico, siga o modelo de chamado abaixo — ele reúne as informações que a equipe precisa para reproduzir o problema sem iterações adicionais.

Como abrir um chamado

[MCP-DEVELOPERS][<título curto do problema>]

CNPJ da empresa sendo operada no MCP:
"<12 dígitos sem pontuação>"

Payload decodado do token (somente os claims — não envie o token completo):
{
  "aud": "https://api.empresas.btgpactual.com/companies/12345612",
  "sub": "412341234",
  "grant_type": "authorization_code",
  "scope": "brn:btg:empresas:banking:collections empresas.btgpactual.com/accounts openid",
  "iss": "https://id.uat.btgpactual.com",
  "session_id": "d1979da7-33ca-49a2-8f82-3a7d1a969c35",
  "exp": 1795030939,
  "iat": 1792438939,
  "client_id": "2299558e-3444-4a51-9992-3078f5999b4b",
  "jti": "T9BlW7IYWUgfZOCyxoxvctM8qZi7aJmuNYKlCRBuqpc"
}

Descrição do problema:
"<O que aconteceu, quando e como reproduzir>"

Mensagem de erro (se houver):
"<Texto exato do erro ou captura de tela>"

Como obter o payload do token

A forma mais simples de obter o seu token decodado para compor o chamado é utilizar o site jwt.io e copiar o "payload"

Nunca envie o token completo

O payload decodado (claims JSON) não é sensível e é seguro de compartilhar. O token completo — as três partes concatenadas — é uma credencial de acesso e não deve ser enviado por e-mail.

Problemas conhecidos — uso local

Diagnósticos que não são expostos diretamente pelo MCP ou que exigem ajuste de configuração local.

Claude Code não reconhece o servidor MCP

Dois motivos são mais frequentes:

1. Servidor desabilitado no settings.local.json

Se o arquivo listar o servidor do BTG Empresas em disabledMcpjsonServers, ele não será carregado:

{
  "enabledMcpjsonServers": [],
  "disabledMcpjsonServers": [
    "btg-empresas-mcp"
  ]
}

Remova "btg-empresas-mcp" da lista disabledMcpjsonServers e reinicie o Claude Code.

2. Arquivo .mcp.json configurado incorretamente

Verifique se o arquivo existe no diretório onde o Claude Code foi aberto e se o campo url aponta para https://mcp.empresas.btgpactual.com/mcp. Veja o modelo completo em Uso local com o Claude Code.

Caso o problema persista, abra um chamado incluindo o conteúdo do .mcp.json (omitindo o valor da variável de ambiente).

Erro 401 — token inválido ou expirado

O servidor retorna 401 quando o token não é aceito pelo BTG Id. Causas mais comuns:

• Token expirado. Gere um novo token via Authorization Code Flow, atualize a variável de ambiente e reinicie o Claude Code.
• Token do fluxo errado. Somente tokens emitidos via Authorization Code são aceitos. Tokens do fluxo Client Credentials não carregam consentimento delegado e são rejeitados.
• Variável de ambiente não exportada. Confirme que BTG_MCP_TOKEN está exportada no mesmo processo em que o Claude Code foi aberto.

Empresa errada sendo operada

Se o assistente opera uma empresa diferente da esperada, a causa está no consentimento registrado no token — o servidor não escolhe a empresa: ele a identifica a partir das claims do token recebido.

• Verifique o campo aud no payload: ele aponta para o CNPJ correto?
• Se o token dá acesso a mais de uma empresa, o assistente pode exibir uma lista para escolha. Confirme que a empresa correta foi selecionada antes de prosseguir.

Operação de escrita executada sem exibir confirmação

Operações de leitura (consultas e listagens) não exigem confirmação — isso é esperado. Apenas operações de escrita (PIX, pagamentos, emissão e cancelamento de boletos) exigem aprovação explícita antes de serem executadas.

Se uma operação de escrita foi executada sem exibir o resumo de confirmação, abra um chamado com o histórico da conversa.

Tempo de conexão expirado durante a chamada

Ocorre quando o servidor MCP não consegue alcançar a API interna do BTG dentro do tempo limite. Tente novamente após alguns segundos. Se o problema for recorrente, abra um chamado.