Windsurf + Dados da B3 via MCP: Configurar o mcp_config.json para Ações Brasileiras no Cascade (2026)

O que é MCP e por que conectar a B3 ao Windsurf

O Cascade já escreve funções, refatora arquivos e roda comandos no terminal. A limitação aparece quando o pedido depende de dados que o modelo não tem: "compare os fundamentos dos cinco maiores bancos da B3". Sem uma fonte conectada, o agente adota nomes de endpoint e de campo inventados, e o código quebra na primeira execução. O MCP fecha essa lacuna com três componentes: o cliente (o Windsurf), o servidor (o bolsai-mcp, um processo local que expõe ferramentas) e um canal JSON-RPC entre os dois. A especificação está em modelcontextprotocol.io.

Durante 2025, o protocolo virou padrão de fato entre editores com IA, e o Windsurf passou a suportá-lo. O servidor bolsai-mcp faz a ponte com a bolsa brasileira, expondo 11 ferramentas que cobrem 350+ ações, 400+ FIIs e 27+ indicadores fundamentalistas calculados a partir da CVM. Para quem desenvolve, o ganho é direto: o Cascade deixa de operar às cegas, consulta a ferramenta, observa a resposta real e escreve o código com os campos corretos. A pergunta "qual o ROE da WEGE3?" deixa de ser chute e passa a vir do número que a API bolsai retorna.

Pré-requisitos

A configuração exige três itens. Nenhum deles é pago no ponto de partida.

• Windsurf instalado em qualquer sistema operacional. O suporte a MCP no Cascade está estável nas versões atuais.
• uv (com o comando uvx): o gerenciador de pacotes Python da Astral. O uvx executa o bolsai-mcp em ambiente isolado, sem instalação global. A instalação está em docs.astral.sh/uv. O runtime exigido é Python 3.10 ou superior, que o próprio uv resolve.
• Uma API key da bolsai, gerada no dashboard com login Google. O plano gratuito libera 200 requisições por dia sem cartão de crédito, suficiente para configurar e testar o fluxo. O plano Pro (R$49/mês) amplia para 10.000 requisições diárias.

Configurando o bolsai-mcp no Windsurf

Há dois caminhos para registrar o servidor. Os dois chegam ao mesmo arquivo mcp_config.json; o que muda é se você passa pela interface ou edita o JSON diretamente.

Pela interface: ícone de MCPs no Cascade → Configure

No painel do Cascade, o canto superior traz um ícone de MCPs (a lista de servidores conectados). Clicar nele abre o gerenciador, com a opção Configure para editar a configuração. O mesmo destino é alcançável pela paleta de comandos: Cmd+Shift+P (ou Ctrl+Shift+P no Windows) e busca por Windsurf: Configure MCP Servers. Como a Codeium ajusta o layout do painel entre releases, a referência autoritativa para o nome exato do botão é a documentação oficial do Windsurf. O conteúdo do JSON permanece estável.

Editando o mcp_config.json na mão

A forma mais previsível é editar o arquivo diretamente. A localização depende do sistema operacional:

• macOS e Linux: ~/.codeium/windsurf/mcp_config.json
• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

O arquivo declara um objeto mcpServers, a chave raiz, com uma entrada por servidor. Para o bolsai-mcp, este é o primeiro bloco funcional. Cole a entrada bolsai e preencha a chave gerada no dashboard:

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "bolsai": {
      "command": "uvx",
      "args": ["bolsai-mcp"],
      "env": {
        "BOLSAI_API_KEY": "sk_sua_chave_aqui"
      }
    }
  }
}

Os três campos são os mesmos de qualquer servidor stdio: command aponta o executável (uvx), args passa os argumentos (bolsai-mcp) e env injeta variáveis de ambiente no processo do servidor. É a mesma estrutura usada no Claude Desktop e no Cursor, o que permite copiar a entrada entre clientes sem alterar nada.

Deixar a chave literal no arquivo funciona, mas vaza o segredo se ele for versionado. O Windsurf resolve variáveis com a sintaxe ${env:NOME}, que lê o valor do ambiente do sistema quando o processo sobe. A versão segura, para quem quer commitar a configuração de um time, troca a linha da chave por "BOLSAI_API_KEY": "${env:BOLSAI_API_KEY}" e mantém a chave real em um export no shell ou em um gerenciador de segredos.

O gotcha do reload: sair e reabrir o Windsurf

Este é o ponto onde a maioria das configurações emperra. O painel Cascade tem um botão de refresh que atualiza a lista de ferramentas, e é natural presumir que ele recarrega tudo. Não recarrega. Mudanças no mcp_config.json (uma entrada nova, uma variável alterada) só passam a valer depois de sair do Windsurf por completo e abrir de novo. Apenas fechar a janela não reinicia os servidores MCP, porque o processo de fundo continua vivo. Feito o restart, volte ao Cascade e confirme que o servidor bolsai e suas ferramentas aparecem na lista.

Um aviso sobre limites do cliente: o Windsurf tem um teto de 100 ferramentas ativas somando todos os servidores MCP, e cerca de 20 chamadas por prompt. Como o bolsai-mcp expõe 11, sobra folga confortável mesmo com outros servidores registrados.

Fluxos no Cascade

Com o servidor ativo, o Cascade decide sozinho quais ferramentas chamar a partir do que você pede em português. Três fluxos cobrem a maioria dos usos de research da B3 dentro do editor.

Screening: "ações com ROE acima de 15% e P/L abaixo de 10"

Filtros quantitativos que exigiam um dashboard viram uma frase. O Cascade traduz o critério em uma chamada à ferramenta screen_stocks, executa e devolve uma tabela ordenada. Todas as decisões de filtragem ficam registradas na conversa, o que torna o resultado reprodutível.

# Prompt no Cascade
Liste as 10 ações da B3 com ROE acima de 15% e P/L
abaixo de 10, ordenadas por ROE decrescente. Mostre
ticker, P/L, ROE e setor.

# Cascade chama: screen_stocks(
#   {"roe_gt": 15, "pl_lt": 10,
#    "sort": "roe", "order": "desc", "limit": 10}
# )

# Resposta resumida da ferramenta (formato ilustrativo)
Ticker    P/L    ROE     Setor
<ticker>  <x>    <x>%    <setor>
<ticker>  <x>    <x>%    <setor>
...       (até 10 linhas conforme o filtro)

A ferramenta screen_stocks mapeia para o endpoint /screener, que aceita operadores _gt (maior que) e _lt (menor que) sobre qualquer campo de fundamentos. Refinar é conversa: "adicione dívida líquida sobre EBITDA abaixo de 2" acrescenta net_debt_ebitda_lt na mesma chamada. O conjunto completo de filtros está em /docs.

Fundamentos e comparação: get_fundamentals + compare_stocks

O segundo fluxo lê um ticker ou compara vários. O pedido natural mistura as duas ferramentas: get_fundamentals para o retrato de cada empresa e compare_stocks para o quadro lado a lado.

# Prompt no Cascade
Compare ITUB4, BBAS3 e BBDC4: P/L, P/VP, ROE e margem
líquida. Diga qual negocia com o maior desconto relativo.

# Cascade chama, em sequência:
# 1. get_fundamentals({"ticker": "ITUB4"})
# 2. get_fundamentals({"ticker": "BBAS3"})
# 3. get_fundamentals({"ticker": "BBDC4"})
#    -> ou, em um único passo:
# compare_stocks({"tickers": ["ITUB4","BBAS3","BBDC4"]})

# Trecho de um retorno de get_fundamentals:
{
  "ticker": "ITUB4",
  "corporate_name": "ITAU UNIBANCO HOLDING S.A.",
  "pl": <valor>,
  "pvp": <valor>,
  "roe": <valor>,
  "net_margin": <valor>,
  "reference_date": "2026-03-31"
}

Porque o Cascade consulta a ferramenta antes de escrever código, ele usa os nomes de campo verdadeiros: pl em vez de pe_ratio, pvp em vez de price_to_book. O campo pl vem calculado com lucro líquido TTM a partir da conta CVM 3.11, e o reference_date indica o balanço usado; a metodologia completa está em /docs. Um detalhe que evita depuração: o dividend yield não está em get_fundamentals; para ele, a ferramenta é get_dividends.

Histórico: get_price_history para retorno e backtest

O terceiro fluxo puxa séries de preço. A ferramenta get_price_history devolve OHLCV com colunas ajustadas por eventos corporativos, indispensável para qualquer cálculo de retorno consistente. Ao pedir um script, o Cascade usa o nome de coluna ajustado correto em vez de assumir um genérico como adj_close:

# historico_vale3.py (gerado pelo Cascade)
import requests
import pandas as pd

BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": "sk_sua_chave_aqui"}

params = {"start": "2023-01-01", "end": "2024-12-31"}
r = requests.get(
    f"{BASE}/stocks/VALE3/history",
    headers=HEADERS, params=params, timeout=30,
)
r.raise_for_status()

df = pd.DataFrame(r.json()["data"]).sort_values("trade_date")
inicio = df["adjusted_close"].iloc[0]
fim = df["adjusted_close"].iloc[-1]
retorno = (fim / inicio - 1) * 100

print(f"Pregões: {len(df)}")
print(f"Retorno ajustado: {retorno:.1f}%")

O uso de adjusted_close em vez do fechamento bruto separa um backtest correto de um enviesado: sem ajuste, um desdobramento produz saltos artificiais na série. A autenticação usa o header X-API-Key. O histórico vai de 1986 até o presente e aceita exportação em CSV com o parâmetro format=csv.

As 11 ferramentas que o Cascade passa a enxergar

Uma vez conectado, o agente do Windsurf ganha acesso a 11 ferramentas do bolsai-mcp. Cada uma mapeia para um ou mais endpoints da API bolsai. A referência completa com parâmetros está em /mcp.

Troubleshooting

Quatro problemas cobrem a maioria das falhas na primeira configuração. O MCP costuma falhar em silêncio, então o primeiro passo de diagnóstico é sempre ler os logs de MCP do Windsurf.

O servidor não aparece no Cascade

Quase sempre é o reload. Confirme que você saiu do Windsurf por completo e reabriu, não apenas fechou a janela. Se ainda assim o bolsai não listar, valide que o JSON é bem formado: uma vírgula sobrando ou uma chave fora do objeto mcpServers impede o parse do arquivo inteiro. O teste mais rápido é rodar uvx bolsai-mcp direto no terminal com a variável exportada; se subir sem erro, o Windsurf também consegue.

uvx: command not found

O gerenciador uv não está instalado ou não está no PATH visto pelo Windsurf. A correção é instalar com curl -LsSf https://astral.sh/uv/install.sh | sh em sistemas Unix (ou o instalador oficial no Windows) e reabrir o editor para que o PATH atualizado seja lido. Em alguns casos vale apontar o caminho absoluto do uvx em command.

401 Unauthorized

A chave está errada ou não chegou ao processo. As causas comuns: um espaço invisível copiado junto do dashboard (copiar com duplo-clique resolve), a variável definida no shell depois de o editor já estar aberto (exige o restart completo) ou a chave revogada e não regenerada. Confira o valor em BOLSAI_API_KEY no mcp_config.json ou no ambiente.

429 Too Many Requests

O limite diário foi atingido. No plano gratuito são 200 requisições em 24h, e uma sessão de research com muitas chamadas encadeadas consome rápido. As saídas são esperar a janela resetar ou migrar para o plano Pro (R$49/mês, 10.000 requisições diárias). O header X-RateLimit-Remaining retornado pela API mostra quanto resta da cota.

O mesmo servidor em outros clientes

O bolsai-mcp não é exclusivo do Windsurf. Como o formato do bloco é compartilhado, migrar a entrada bolsai entre editores é copiar o objeto de um arquivo para o outro, e a mesma BOLSAI_API_KEY autentica todos.

• O guia completo do bolsai-mcp com Claude cobre a configuração no Claude Desktop e a análise conversacional.
• Para produzir e rodar scripts com um agente de IA, o mesmo servidor no Cursor segue o mesmo formato de mcp.json.
• No VS Code com o GitHub Copilot a chave raiz muda para servers e as ferramentas só aparecem em agent mode.
• Para quem vive no shell, o mesmo servidor roda no terminal com o Claude Code via claude mcp add.
• Para escolher entre as opções de dados, vale a comparação dos MCP servers de dados da B3 lado a lado.

Perguntas frequentes

Onde fica o mcp_config.json do Windsurf?

No macOS e Linux, o arquivo fica em ~/.codeium/windsurf/mcp_config.json. No Windows, em %USERPROFILE%\.codeium\windsurf\mcp_config.json. A forma mais direta de abri-lo é pelo painel Cascade: clique no ícone de MCPs no canto superior e escolha Configure, ou use a paleta de comandos com Cmd+Shift+P e busque por Windsurf: Configure MCP Servers. O arquivo declara um objeto mcpServers com uma chave por servidor.

Preciso reiniciar o Windsurf após configurar o MCP?

Sim, e o detalhe é importante. O botão de refresh do painel Cascade atualiza a lista de ferramentas, mas não recarrega mudanças no mcp_config.json. Para que uma entrada nova ou uma variável de ambiente alterada passem a valer, é preciso sair do Windsurf por completo e abrir de novo. Apenas fechar a janela do editor não reinicia os servidores MCP.

O bolsai-mcp funciona no Cascade sem instalar nada?

Quase. O servidor é executado com uvx, o runner do gerenciador uv, que baixa e roda o pacote bolsai-mcp em ambiente isolado sem instalação global. O único pré-requisito é ter o uv instalado e um runtime Python 3.10 ou superior, que o próprio uv resolve. Não é necessário clonar repositório nem manter um virtualenv: o Windsurf sobe o processo com o comando declarado no mcp_config.json.

Quais ferramentas de dados da B3 ficam disponíveis?

O bolsai-mcp expõe 11 ferramentas ao Cascade: get_stock_quote, get_fundamentals, compare_stocks, get_dividends, search_companies, list_sectors, get_price_history, get_fii_details, get_macro_indicator, get_financial_statements e screen_stocks. Elas cobrem cotações de fechamento, 27+ indicadores fundamentalistas, dividendos, FIIs, séries macro do Banco Central e demonstrações financeiras da CVM. A referência completa está na página /mcp.

Leia também

Referências

• Documentação oficial do Windsurf: Cascade MCP Integration (caminho do mcp_config.json, UI do Cascade e recarga por reabrir o editor).
• modelcontextprotocol.io (especificação do Model Context Protocol).
• Documentação do bolsai-mcp (as 11 ferramentas e seus parâmetros).

O conteúdo deste artigo tem caráter educacional e técnico, com data de referência 14 de julho de 2026. Os caminhos de arquivo e a interface do Windsurf podem mudar entre versões; a documentação oficial é a fonte autoritativa. Os dados citados refletem valores públicos disponíveis no momento da consulta à API e podem mudar. Nada aqui constitui recomendação de compra ou venda de ativos financeiros. Nomes de produtos e marcas pertencem aos respectivos titulares; Windsurf e Cascade são marcas da Codeium, e Claude e Model Context Protocol são marcas da Anthropic PBC.