# MCP

## Conectar seu assistente

Tenha em mãos uma [chave de integração](/docs/guide/key) com acesso ao Finance. Você encontra suas chaves no [Console HG Brasil](https://console.hgbrasil.com/).

Copie o endereço do servidor:

```text
https://mcp.hgbrasil.com/
```

Escolha seu assistente para ver o passo a passo.

<tabs>
<tabs-item label="ChatGPT">
<steps level="4">

#### Abra os plugins

No ChatGPT pela web, acesse [Plugins](https://chatgpt.com/plugins) e clique em **+ → Add custom MCP server**.

#### Adicione a HG Brasil

Use o nome **HG Brasil**, cole o endereço do servidor e selecione **OAuth**. Use a descoberta e o registro automático de cliente, quando solicitados.

#### Autorize a conexão

Conclua a criação do plugin e, na tela da HG Brasil, confira as permissões, informe sua chave e clique em **Autorizar conexão**.

#### Use na conversa

Inicie uma conversa, digite **@** e selecione **HG Brasil**.

</steps>

Se a opção de adicionar um servidor não aparecer, confira as permissões da conta ou do workspace. [Ver o guia do ChatGPT](https://developers.openai.com/api/docs/guides/custom-mcp-server).

</tabs-item>

<tabs-item label="Claude">
<steps level="4">

#### Abra os conectores

No Claude, acesse **Customize → Connectors** e clique em **+ Add → Add custom connector**.

#### Adicione a HG Brasil

Use o nome **HG Brasil** e cole o endereço do servidor. Confira o OAuth detectado e use a identidade publicada do Claude ou o registro automático, se solicitado.

#### Autorize a conexão

Adicione o conector e clique em **Connect**. Na tela da HG Brasil, confira as permissões, informe sua chave e autorize.

#### Use na conversa

Abra **+ → Connectors** e habilite **HG Brasil**.

</steps>

Em equipes, o administrador adiciona o conector em **Organization settings → Connectors**. [Ver o guia do Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

</tabs-item>

<tabs-item label="Gemini">

O app web libera apps personalizados para contas Google pessoais de maiores de 18 anos nos EUA, em inglês e com o histórico de atividade ativado. [Confira a disponibilidade no Google](https://support.google.com/gemini/answer/17209137?hl=en).

<steps level="4">

#### Abra os apps conectados

No Gemini pela web, acesse **Settings → Connected Apps**. Em algumas versões, essa área fica em **Personal Intelligence → Connected Apps**.

#### Adicione a HG Brasil

Em **Custom apps**, adicione um app personalizado, cole o endereço do servidor e avance.

#### Autorize e use

Conclua o OAuth na tela da HG Brasil. Depois, digite **@** na conversa e selecione o app conectado.

</steps>

<accordion>
<accordion-item label="Conectar pelo Gemini CLI">

Com o [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) instalado, adicione o servidor pelo terminal:

```bash
gemini mcp add --transport http hg-brasil https://mcp.hgbrasil.com/
```

Abra o CLI com `gemini` e execute na sessão interativa:

```text
/mcp auth hg-brasil
```

Conclua a autorização no navegador. Use `/mcp` para conferir a conexão.

</accordion-item>
</accordion>
</tabs-item>
</tabs>

<tip icon="tabler:key">

Informe sua chave **somente na autorização da HG Brasil**, aberta pelo aplicativo. Não a cole no chat nem acrescente a chave ou caminhos ao endereço do servidor.

</tip>

## Faça sua primeira consulta

Habilite a conexão e experimente:

```text
Use a HG Brasil para consultar PETR4 e VALE3. Mostre preço, moeda,
variação e horário de atualização, quando disponíveis.
```

<accordion>
<accordion-item label="Buscar Bitcoin em dólar">

```text
Busque Bitcoin em dólar na HG Brasil e consulte a cotação do ativo
retornado. Mostre também a fonte e o identificador.
```

</accordion-item>

<accordion-item label="Consultar o histórico de uma ação">

```text
Consulte o histórico diário de B3:PETR4 nos últimos 30 dias e
apresente os preços de fechamento, sem preencher dias sem dados.
```

</accordion-item>

<accordion-item label="Acompanhar SELIC e IPCA">

```text
Consulte BCB:SELIC e IBGE:IPCA nos últimos 90 dias. Separe as séries
com as unidades e os períodos informados pela HG Brasil.
```

</accordion-item>
</accordion>

## Ferramentas do Finance

São **14 ferramentas**, sujeitas às permissões da sua chave. O assistente escolhe quais usar a partir da sua pergunta.

<accordion>
<accordion-item label="Ver as 14 ferramentas">
<table>
<thead>
  <tr>
    <th>
      Ferramenta
    </th>
    
    <th>
      O que consulta
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        finance_get_market_summary
      </code>
    </td>
    
    <td>
      Resumo dos ativos e indicadores selecionados pela API.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_search_assets
      </code>
    </td>
    
    <td>
      Busca de ativos por nome, símbolo, fonte ou categoria.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_quotes
      </code>
    </td>
    
    <td>
      Cotações de ativos e componentes do Ibovespa.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_history
      </code>
    </td>
    
    <td>
      Histórico de preços por ticker.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_historical
      </code>
    </td>
    
    <td>
      Histórico por símbolo, com formato de resposta próprio.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_indicators
      </code>
    </td>
    
    <td>
      Séries de indicadores econômicos.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_dividends
      </code>
    </td>
    
    <td>
      Proventos, com filtros pela data-com.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_splits
      </code>
    </td>
    
    <td>
      Desdobramentos e grupamentos, com filtros pela data-com.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_bonds
      </code>
    </td>
    
    <td>
      Cadastro e detalhes de títulos da fonte TREASURYBR.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_funds
      </code>
    </td>
    
    <td>
      Cadastro e detalhes de fundos da fonte CVM.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_fundamentals
      </code>
    </td>
    
    <td>
      Fundamentos de empresas.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_balance_sheets
      </code>
    </td>
    
    <td>
      Balanços patrimoniais.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_income_statements
      </code>
    </td>
    
    <td>
      Demonstrações de resultados (DRE).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        finance_get_cash_flows
      </code>
    </td>
    
    <td>
      Demonstrações de fluxos de caixa.
    </td>
  </tr>
</tbody>
</table>

Use `tools/list` para conferir os argumentos na versão conectada. As ferramentas aceitam `locale` com `pt-br` ou `en`.

</accordion-item>

<accordion-item label="Quais identificadores usar?">

Use o ticker completo retornado pela busca, como `B3:PETR4`, `CRYPTO:BTCUSD` ou `BCB:SELIC`. Para títulos e fundos, não construa o identificador a partir do nome comercial.

A exceção é `finance_get_historical`, que recebe `symbols`, como `PETR4`, sem a fonte.

</accordion-item>
</accordion>

## Integrar na sua aplicação

Veja uma chamada de cotação nas mesmas linguagens dos exemplos da API.

<accordion>
<accordion-item label="Preparar a conexão OAuth">

Use um [SDK MCP](https://modelcontextprotocol.io/docs/sdk) para autorizar seu próprio cliente e inicializar a conexão. O SDK cuida de `initialize`, `notifications/initialized`, sessões e respostas JSON ou SSE.

<table>
<thead>
  <tr>
    <th>
      Configuração
    </th>
    
    <th>
      Valor
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Transporte
    </td>
    
    <td>
      Streamable HTTP
    </td>
  </tr>
  
  <tr>
    <td>
      Autenticação
    </td>
    
    <td>
      Authorization Code com PKCE
    </td>
  </tr>
  
  <tr>
    <td>
      Permissão
    </td>
    
    <td>
      <code>
        finance:read
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Renovação, quando solicitada
    </td>
    
    <td>
      <code>
        offline_access
      </code>
    </td>
  </tr>
</tbody>
</table>

Os metadados OAuth estão em `https://mcp.hgbrasil.com/.well-known/oauth-authorization-server`.

Defina as variáveis no ambiente do servidor:

<table>
<thead>
  <tr>
    <th>
      Variável
    </th>
    
    <th>
      Valor
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        MCP_ACCESS_TOKEN
      </code>
    </td>
    
    <td>
      Access token do seu cliente OAuth. <strong>
        Não é a chave HG Brasil.
      </strong>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_PROTOCOL_VERSION
      </code>
    </td>
    
    <td>
      Versão negociada em <code>
        initialize
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        MCP_SESSION_ID
      </code>
    </td>
    
    <td>
      Cabeçalho <code>
        Mcp-Session-Id
      </code>
      
      , se retornado. Omita quando não houver sessão.
    </td>
  </tr>
</tbody>
</table>

Sua aplicação faz sua própria autorização; não precisa copiar tokens do ChatGPT, Claude ou Gemini.

</accordion-item>

<accordion-item label="Consultar PETR4 e VALE3 em código">

Estes exemplos enviam uma chamada HTTP em uma **conexão já autorizada e inicializada**. O login OAuth e o gerenciamento da conexão ficam a cargo do seu cliente MCP.

Salve o corpo da consulta como **quote.json**:

```json [quote.json]
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "finance_get_quotes",
    "arguments": {
      "tickers": ["B3:PETR4", "B3:VALE3"],
      "locale": "pt-br"
    }
  }
}
```

Envie o arquivo ao servidor MCP:

<code-group>

```bash [cURL]
curl --fail-with-body https://mcp.hgbrasil.com/ \
  -H "Authorization: Bearer $MCP_ACCESS_TOKEN" \
  -H "MCP-Protocol-Version: $MCP_PROTOCOL_VERSION" \
  ${MCP_SESSION_ID:+-H "Mcp-Session-Id: $MCP_SESSION_ID"} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data-binary @quote.json
```

```javascript [JavaScript]
import { readFile } from 'node:fs/promises'

const headers = {
  'Authorization': `Bearer ${process.env.MCP_ACCESS_TOKEN}`,
  'MCP-Protocol-Version': process.env.MCP_PROTOCOL_VERSION,
  'Content-Type': 'application/json',
  'Accept': 'application/json, text/event-stream'
}

if (process.env.MCP_SESSION_ID) {
  headers['Mcp-Session-Id'] = process.env.MCP_SESSION_ID
}

const response = await fetch('https://mcp.hgbrasil.com/', {
  method: 'POST',
  headers,
  body: await readFile('quote.json', 'utf8')
})

if (!response.ok) throw new Error(`HTTP ${response.status}`)

console.log(await response.text())
```

```php [PHP]
<?php
$headers = [
    'Authorization: Bearer ' . getenv('MCP_ACCESS_TOKEN'),
    'MCP-Protocol-Version: ' . getenv('MCP_PROTOCOL_VERSION'),
    'Content-Type: application/json',
    'Accept: application/json, text/event-stream'
];

if (getenv('MCP_SESSION_ID')) {
    $headers[] = 'Mcp-Session-Id: ' . getenv('MCP_SESSION_ID');
}

$request = curl_init('https://mcp.hgbrasil.com/');
curl_setopt_array($request, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => file_get_contents('quote.json'),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FAILONERROR => true
]);

$response = curl_exec($request);
if ($response === false) {
    throw new RuntimeException(curl_error($request));
}
curl_close($request);
echo $response;
```

```python [Python]
import os
from pathlib import Path
from urllib.request import Request, urlopen

headers = {
    'Authorization': f"Bearer {os.environ['MCP_ACCESS_TOKEN']}",
    'MCP-Protocol-Version': os.environ['MCP_PROTOCOL_VERSION'],
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream'
}

if os.environ.get('MCP_SESSION_ID'):
    headers['Mcp-Session-Id'] = os.environ['MCP_SESSION_ID']

request = Request(
    'https://mcp.hgbrasil.com/',
    data=Path('quote.json').read_bytes(),
    headers=headers,
    method='POST'
)

with urlopen(request, timeout=30) as response:
    print(response.read().decode('utf-8'))
```

```ruby [Ruby]
require 'net/http'

uri = URI('https://mcp.hgbrasil.com/')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = "Bearer #{ENV.fetch('MCP_ACCESS_TOKEN')}"
request['MCP-Protocol-Version'] = ENV.fetch('MCP_PROTOCOL_VERSION')
request['Content-Type'] = 'application/json'
request['Accept'] = 'application/json, text/event-stream'
request['Mcp-Session-Id'] = ENV['MCP_SESSION_ID'] if ENV['MCP_SESSION_ID']
request.body = File.read('quote.json')

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end

response.value
puts response.body
```

```java [Java]
import java.net.URI;
import java.net.http.*;
import java.nio.file.*;

class Example {
    public static void main(String[] args) throws Exception {
        var builder = HttpRequest.newBuilder()
            .uri(URI.create("https://mcp.hgbrasil.com/"))
            .header("Authorization", "Bearer " +
                System.getenv("MCP_ACCESS_TOKEN"))
            .header("MCP-Protocol-Version",
                System.getenv("MCP_PROTOCOL_VERSION"))
            .header("Content-Type", "application/json")
            .header("Accept", "application/json, text/event-stream")
            .POST(HttpRequest.BodyPublishers.ofFile(Path.of("quote.json")));

        if (System.getenv("MCP_SESSION_ID") != null) {
            builder.header("Mcp-Session-Id", System.getenv("MCP_SESSION_ID"));
        }

        var response = HttpClient.newHttpClient().send(
            builder.build(), HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException("HTTP " + response.statusCode());
        }
        System.out.println(response.body());
    }
}
```

```csharp [C#]
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("MCP_ACCESS_TOKEN"));
client.DefaultRequestHeaders.Add("MCP-Protocol-Version",
    Environment.GetEnvironmentVariable("MCP_PROTOCOL_VERSION"));
client.DefaultRequestHeaders.Add("Accept",
    "application/json, text/event-stream");

var sessionId = Environment.GetEnvironmentVariable("MCP_SESSION_ID");
if (!string.IsNullOrEmpty(sessionId)) {
    client.DefaultRequestHeaders.Add("Mcp-Session-Id", sessionId);
}

using var body = new StringContent(
    await File.ReadAllTextAsync("quote.json"),
    Encoding.UTF8, "application/json");
using var response = await client.PostAsync("https://mcp.hgbrasil.com/", body);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

</code-group>

Use Node.js 18 ou superior com um arquivo `.mjs`, Python 3, a extensão cURL no PHP, Java 11 ou superior ou um projeto .NET com imports implícitos para C#.

Os exemplos exibem a resposta como texto, preservando JSON e SSE. Em um cliente completo, confira também erros JSON-RPC e `result.isError`, mesmo com HTTP `200`.

</accordion-item>
</accordion>

## Ajuda

<accordion>
<accordion-item label="Como trocar a chave ou desconectar?">

Para trocar a chave, remova a conexão anterior e faça uma nova autorização. Para encerrar o acesso, use os controles de desconexão ou revogação do aplicativo.

</accordion-item>

<accordion-item label="Como funcionam atualização e consumo?">

As consultas seguem os limites e as permissões da sua chave. Uma pergunta pode acionar várias ferramentas. `api_calls` informa as requisições iniciadas naquela execução, não o saldo da conta.

`retrieved_at` é o horário da consulta MCP, não a atualização do dado financeiro. Confira as moedas, unidades e datas retornadas. Resultados podem ser parciais; valores ausentes não significam zero.

</accordion-item>

<accordion-item label="Não consegui conectar ou consultar">
<table>
<thead>
  <tr>
    <th>
      Situação
    </th>
    
    <th>
      Como resolver
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      O aplicativo não conecta
    </td>
    
    <td>
      Confira a URL raiz e o suporte a Streamable HTTP com OAuth. Verifique também as permissões da conta no aplicativo.
    </td>
  </tr>
  
  <tr>
    <td>
      Acesso expirado ou conexão não autorizada
    </td>
    
    <td>
      Reconecte pelo aplicativo e refaça a autorização.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        INVALID_API_KEY
      </code>
    </td>
    
    <td>
      Confira a chave no Console e autorize novamente.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        UNAUTHORIZED_KEY
      </code>
    </td>
    
    <td>
      Confira as permissões do recurso, do ativo e do período no seu plano.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        INVALID_TICKER
      </code>
    </td>
    
    <td>
      Busque o ativo e use o identificador completo retornado.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        RATE_LIMITED
      </code>
    </td>
    
    <td>
      Aguarde e confira os limites da sua conta.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TIMEOUT
      </code>
      
       ou <code>
        RESPONSE_TOO_LARGE
      </code>
    </td>
    
    <td>
      Reduza a quantidade de ativos, o período ou os campos da consulta.
    </td>
  </tr>
</tbody>
</table>

Se o problema persistir, procure a HG Brasil pelo [Console](https://console.hgbrasil.com/) e informe a ferramenta e o código do erro, sem enviar sua chave ou tokens.

</accordion-item>
</accordion>
