Skip to main content

How the MCP server works

This page is a brief overview of how the server works, enough to understand what happens when you use MCP. For the practical step-by-step, go directly to Local use with Claude Code.

Authentication is delegated to BTG Id​

The MCP server does not issue tokens and does not validate credentials on its own. Authentication is handled by BTG Id, exactly as in direct API access. The MCP server simply receives the token that arrives with each request, identifies the company from it, and forwards the call to the internal server.

Each request is independent​

The server stores no session and no state between calls. Each request carries its own token and is self-contained. That is what keeps usage straightforward: all the server needs is a valid token issued by BTG Id.

Read and write operations​

The operations exposed by the server fall into two categories:

  • Read — queries and listings. They do not move money and do not change the state of entities.
  • Write — operations that move money or change state, such as a Pix transfer, a payment, or issuing or cancelling a bank slip.

Every write operation requires explicit human confirmation before it is executed. The assistant presents an operation summary: company, amount, payee, and date, with the document number masked, and only proceeds after your deliberate approval. This is covered in more depth in Security and best practices.

What happens in a call​

In summary, when you ask the assistant for something:

  1. The assistant selects the appropriate operation and sends it to the MCP server, along with your token.
  2. The server identifies the company from the token.
  3. The server calls the BTG Empresas API on behalf of that company.
  4. If it is a write operation, confirmation happens before execution.
  5. The result is returned to the conversation.