Saltar al contenido principal

Soporte

Canal de atención​

El soporte para el MCP se gestiona por correo electrónico, a través del canal de implantaciones: ImplantacaoEmpresas@btgpactual.com.

Para agilizar el diagnóstico, siga el modelo de ticket que se indica a continuación — reúne la información que el equipo necesita para reproducir el problema sin iteraciones adicionales.

Cómo abrir un ticket​

[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>"
Cómo obtener el payload del token

La forma más sencilla de obtener su token decodado para completar el ticket es pegarlo en jwt.io y copiar la sección "Payload".

Nunca envíe el token completo

El payload decodificado (claims JSON) no es sensible y es seguro de compartir. El token completo — las tres partes concatenadas — es una credencial de acceso y no debe enviarse por correo electrónico.

Problemas conocidos — uso local​

Diagnósticos que no están expuestos directamente por el MCP o que requieren ajuste de configuración local.

Claude Code no reconoce el servidor MCP​

Dos motivos son más frecuentes:

1. Servidor deshabilitado en settings.local.json

Si el archivo lista el servidor de BTG Empresas en disabledMcpjsonServers, no se cargará:

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

Elimine "btg-empresas-mcp" de la lista disabledMcpjsonServers y reinicie el Claude Code.

2. Archivo .mcp.json configurado incorrectamente

Verifique que el archivo existe en el directorio donde se abrió el Claude Code y que el campo url apunta a https://mcp.empresas.btgpactual.com/mcp. Consulte el modelo completo en Uso local con el Claude Code.

Si el problema persiste, abra un ticket incluyendo el contenido del .mcp.json (omitiendo el valor de la variable de entorno).

Error 401 — token inválido o vencido​

El servidor devuelve 401 cuando el token no es aceptado por el BTG Id. Causas más comunes:

  • Token vencido. Genere un nuevo token mediante el Authorization Code Flow, actualice la variable de entorno y reinicie el Claude Code.
  • Token del flujo incorrecto. Solo se aceptan tokens emitidos mediante Authorization Code. Los tokens del flujo Client Credentials no llevan consentimiento delegado y son rechazados.
  • Variable de entorno no exportada. Confirme que BTG_MCP_TOKEN está exportada en el mismo proceso en que se abrió el Claude Code.

Empresa incorrecta siendo operada​

Si el asistente opera una empresa diferente a la esperada, la causa está en el consentimiento registrado en el token — el servidor no elige la empresa: la identifica a partir de los claims del token recibido.

  • Verifique el campo aud en el payload: ¿apunta al CNPJ correcto?
  • Si el token da acceso a más de una empresa, el asistente puede mostrar una lista para que elija. Confirme que la empresa correcta fue seleccionada antes de continuar.

Operación de escritura ejecutada sin mostrar confirmación​

Las operaciones de lectura (consultas y listados) no requieren confirmación — esto es lo esperado. Solo las operaciones de escritura (PIX, pagos, emisión y cancelación de boletos) requieren aprobación explícita antes de ejecutarse.

Si una operación de escritura fue ejecutada sin mostrar el resumen de confirmación, abra un ticket con el historial de la conversación.

Tiempo de conexión expirado durante la llamada​

Ocurre cuando el servidor MCP no puede alcanzar la API interna de BTG dentro del tiempo límite. Intente nuevamente después de unos segundos. Si el problema es recurrente, abra un ticket.