Skip to main content

Support

Support channel​

MCP support is handled by email, through the deployment channel: ImplantacaoEmpresas@btgpactual.com.

To speed up diagnosis, use the ticket template below — it gathers the information the team needs to reproduce the issue without additional back-and-forth.

Opening a support 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>"
How to get the token payload

The easiest way to get your decoded token to fill in the ticket is to paste it into jwt.io and copy the "Payload" section.

Never send the complete token

The decoded payload (JSON claims) is not sensitive and is safe to share. The complete token — all three parts concatenated — is an access credential and must not be sent by email.

Known issues — local use​

Diagnostics not surfaced directly by the MCP server or that require local configuration adjustments.

Claude Code does not recognize the MCP server​

Two causes are most common:

1. Server disabled in settings.local.json

If the file lists the BTG Empresas server under disabledMcpjsonServers, it will not be loaded:

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

Remove "btg-empresas-mcp" from the disabledMcpjsonServers list and restart Claude Code.

2. .mcp.json file configured incorrectly

Verify the file exists in the directory where you opened Claude Code and that the url field points to https://mcp.empresas.btgpactual.com/mcp. See the full template in Local use with Claude Code.

If the issue persists, open a ticket including the contents of your .mcp.json file (omitting the environment variable value).

Error 401 — invalid or expired token​

The server returns 401 when the token is not accepted by BTG Id. Most common causes:

  • Expired token. Generate a new token via the Authorization Code Flow, update the environment variable, and restart Claude Code.
  • Token from the wrong flow. Only tokens issued via the Authorization Code flow are accepted. Client Credentials tokens do not carry delegated user consent and are rejected.
  • Environment variable not exported. Confirm that BTG_MCP_TOKEN is exported in the same process where Claude Code was opened.

Wrong company being operated​

If the assistant is operating a different company than expected, the cause is in the consent recorded in the token — the server does not choose the company: it identifies it from the claims in the received token.

  • Check the aud field in the payload: does it point to the correct CNPJ?
  • If the token grants access to more than one company, the assistant may display a list for you to choose from. Confirm the correct company is selected before proceeding.

Write operation executed without showing confirmation​

Read operations (queries and listings) do not require confirmation — that is expected. Only write operations (Pix transfers, payments, bank slip issuance and cancellation) require explicit approval before being executed.

If a write operation was executed without displaying the confirmation summary, open a ticket with the conversation history.

Connection timeout during a call​

This occurs when the MCP server cannot reach the BTG internal API within the time limit. Try again after a few seconds. If the issue persists, open a ticket.