MCP
Conectar seu assistente
Tenha em mãos uma chave de integração com acesso ao Finance. Você encontra suas chaves no Console HG Brasil.
Copie o endereço do servidor:
https://mcp.hgbrasil.com/
Escolha seu assistente para ver o passo a passo.
Abra os plugins
No ChatGPT pela web, acesse 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.
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.
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.
Em equipes, o administrador adiciona o conector em Organization settings → Connectors. Ver o guia do Claude.
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.
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.
Com o Gemini CLI instalado, adicione o servidor pelo terminal:
gemini mcp add --transport http hg-brasil https://mcp.hgbrasil.com/
Abra o CLI com gemini e execute na sessão interativa:
/mcp auth hg-brasil
Conclua a autorização no navegador. Use /mcp para conferir a conexão.
Faça sua primeira consulta
Habilite a conexão e experimente:
Use a HG Brasil para consultar PETR4 e VALE3. Mostre preço, moeda,
variação e horário de atualização, quando disponíveis.
Busque Bitcoin em dólar na HG Brasil e consulte a cotação do ativo
retornado. Mostre também a fonte e o identificador.
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.
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.
Ferramentas do Finance
São 14 ferramentas, sujeitas às permissões da sua chave. O assistente escolhe quais usar a partir da sua pergunta.
| Ferramenta | O que consulta |
|---|---|
finance_get_market_summary | Resumo dos ativos e indicadores selecionados pela API. |
finance_search_assets | Busca de ativos por nome, símbolo, fonte ou categoria. |
finance_get_quotes | Cotações de ativos e componentes do Ibovespa. |
finance_get_history | Histórico de preços por ticker. |
finance_get_historical | Histórico por símbolo, com formato de resposta próprio. |
finance_get_indicators | Séries de indicadores econômicos. |
finance_get_dividends | Proventos, com filtros pela data-com. |
finance_get_splits | Desdobramentos e grupamentos, com filtros pela data-com. |
finance_get_bonds | Cadastro e detalhes de títulos da fonte TREASURYBR. |
finance_get_funds | Cadastro e detalhes de fundos da fonte CVM. |
finance_get_fundamentals | Fundamentos de empresas. |
finance_get_balance_sheets | Balanços patrimoniais. |
finance_get_income_statements | Demonstrações de resultados (DRE). |
finance_get_cash_flows | Demonstrações de fluxos de caixa. |
Use tools/list para conferir os argumentos na versão conectada. As ferramentas aceitam locale com pt-br ou en.
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.
Integrar na sua aplicação
Veja uma chamada de cotação nas mesmas linguagens dos exemplos da API.
Use um SDK MCP 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.
| Configuração | Valor |
|---|---|
| Transporte | Streamable HTTP |
| Autenticação | Authorization Code com PKCE |
| Permissão | finance:read |
| Renovação, quando solicitada | offline_access |
Os metadados OAuth estão em https://mcp.hgbrasil.com/.well-known/oauth-authorization-server.
Defina as variáveis no ambiente do servidor:
| Variável | Valor |
|---|---|
MCP_ACCESS_TOKEN | Access token do seu cliente OAuth. Não é a chave HG Brasil. |
MCP_PROTOCOL_VERSION | Versão negociada em initialize. |
MCP_SESSION_ID | Cabeçalho Mcp-Session-Id, se retornado. Omita quando não houver sessão. |
Sua aplicação faz sua própria autorização; não precisa copiar tokens do ChatGPT, Claude ou Gemini.
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:
{
"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:
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
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
$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;
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'))
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
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());
}
}
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());
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.
Ajuda
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.
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.
| Situação | Como resolver |
|---|---|
| O aplicativo não conecta | Confira a URL raiz e o suporte a Streamable HTTP com OAuth. Verifique também as permissões da conta no aplicativo. |
| Acesso expirado ou conexão não autorizada | Reconecte pelo aplicativo e refaça a autorização. |
INVALID_API_KEY | Confira a chave no Console e autorize novamente. |
UNAUTHORIZED_KEY | Confira as permissões do recurso, do ativo e do período no seu plano. |
INVALID_TICKER | Busque o ativo e use o identificador completo retornado. |
RATE_LIMITED | Aguarde e confira os limites da sua conta. |
TIMEOUT ou RESPONSE_TOO_LARGE | Reduza a quantidade de ativos, o período ou os campos da consulta. |
Se o problema persistir, procure a HG Brasil pelo Console e informe a ferramenta e o código do erro, sem enviar sua chave ou tokens.