# Servidor MCP para IAs
URL: /docs/mcp.mdx

Integre dados financeiros brasileiros em tempo real com assistentes de IA usando o Model Context Protocol (MCP). Funciona com Claude Code, Claude Desktop, Cursor, VS Code, n8n, e 100+ clientes compatíveis.

***

title: Servidor MCP para IAs
description:
Integre dados financeiros brasileiros em tempo real com assistentes de IA
usando o Model Context Protocol (MCP). Funciona com Claude Code, Claude
Desktop, Cursor, VS Code, n8n, e 100+ clientes compatíveis.
howToSteps:

* name: 'Obtenha seu token'
  text: 'Crie uma conta gratuita em brapi.dev e gere sua chave de API no dashboard.'
* name: 'Configure o servidor MCP'
  text: 'Adicione a configuração do servidor brapi no seu cliente MCP (Claude Code, Cursor, VS Code, etc.) usando seu token.'
* name: 'Faça consultas em linguagem natural'
  text: 'Pergunte sobre ações, criptomoedas, câmbio e indicadores econômicos brasileiros diretamente para o assistente de IA.'
  howToTools:
* 'Cliente MCP compatível (Claude Code, Claude Desktop, Cursor, VS Code, n8n, etc.)'
* 'Node.js >= v18.0.0 (para alguns clientes)'
  howToSupplies:
* 'Conta brapi.dev (gratuita)'
* 'Token de API brapi.dev'

***

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';

O **Model Context Protocol (MCP)** permite que assistentes de IA acessem dados
externos em tempo real. O servidor MCP da Brapi conecta LLMs aos dados
financeiros brasileiros, permitindo consultas de cotações, históricos e
indicadores econômicos durante conversas.

## Início Rápido

<Steps>
  ### Obtenha seu Token

  1. Acesse [brapi.dev](https://brapi.dev) e crie uma conta gratuita
  2. No dashboard, gere sua chave de API
  3. Copie o token para usar na configuração

  ### Configure seu Cliente

  Escolha seu cliente MCP e siga as instruções específicas abaixo.

  ### Faça sua Primeira Consulta

  Com o MCP configurado, pergunte ao assistente:

  ```txt
  Qual é a cotação atual da PETR4?
  ```
</Steps>

## Configuração por Cliente

<Tabs items={['Claude Code', 'Claude Desktop', 'Cursor', 'VS Code', 'n8n', 'Outros']}>
  <Tab value="Claude Code">
    ### Claude Code (CLI)

    O Claude Code usa comandos CLI para gerenciar servidores MCP:

    ```bash
    claude mcp add --transport http --header "Authorization:Bearer SEU_TOKEN" brapi https://brapi.dev/api/mcp/mcp
    ```

    **Verificar instalação:**

    ```bash
    claude mcp list
    ```

    **Remover servidor:**

    ```bash
    claude mcp remove brapi
    ```

    <Callout type="info">
      **Configuração Global vs. Projeto**

      * Sem flags: configuração local (`~/.claude.json`)
      * Com `--scope project`: configuração de projeto (`.claude/settings.json`)
      * Com `--scope user`: configuração global do usuário

      ```bash
      claude mcp add --transport http --header "Authorization:Bearer SEU_TOKEN" --scope project brapi https://brapi.dev/api/mcp/mcp
      ```
    </Callout>
  </Tab>

  <Tab value="Claude Desktop">
    ### Claude Desktop

    Edite o arquivo de configuração:

    * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer SEU_TOKEN"
          ]
        }
      }
    }
    ```

    Reinicie o Claude Desktop após salvar.
  </Tab>

  <Tab value="Cursor">
    ### Cursor

    Configure em `~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (projeto):

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer ${BRAPI_API_KEY}"
          ],
          "env": {
            "BRAPI_API_KEY": "SEU_TOKEN"
          }
        }
      }
    }
    ```

    Reinicie o Cursor após salvar.
  </Tab>

  <Tab value="VS Code">
    ### VS Code (Copilot)

    Configure em `.vscode/mcp.json` ou nas configurações do usuário:

    ```json
    {
      "mcp": {
        "servers": {
          "brapi": {
            "command": "npx",
            "args": [
              "mcp-remote",
              "https://brapi.dev/api/mcp/mcp",
              "--header",
              "Authorization:Bearer SEU_TOKEN"
            ]
          }
        }
      }
    }
    ```

    <Callout type="info">
      **Requisitos**

      * VS Code 1.99+ ou VS Code Insiders
      * Extensão GitHub Copilot atualizada
      * Habilite `chat.mcp.enabled` nas configurações
    </Callout>
  </Tab>

  <Tab value="n8n">
    ### n8n (Automação de Workflows)

    O n8n suporta MCP nativamente através do **MCP Client Tool** node, permitindo
    criar automações com dados financeiros brasileiros.

    **Configuração:**

    1. Adicione um node **AI Agent** ao seu workflow
    2. Conecte um **MCP Client Tool** node
    3. Configure as credenciais MCP:

    ```json
    {
      "serverUrl": "https://brapi.dev/api/mcp/mcp",
      "authentication": "Bearer Token",
      "token": "SEU_TOKEN"
    }
    ```

    **Exemplo de Workflow:**

    ```
    Trigger → AI Agent → MCP Client Tool (brapi) → Output
    ```

    **Casos de Uso:**

    * Alertas automáticos de variação de preço
    * Relatórios diários de carteira
    * Integração com Slack/Discord para notificações
    * Análise automatizada de mercado

    <Callout type="info">
      **Documentação n8n**

      Consulte a
      [documentação oficial do MCP Client Tool](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.mcpclienttool/)
      para mais detalhes.
    </Callout>
  </Tab>

  <Tab value="Outros">
    ### Outros Clientes Compatíveis

    O servidor MCP da Brapi funciona com qualquer cliente compatível com o
    protocolo:

    **IDEs e Editores:**

    * **Windsurf** - IDE com IA integrada
    * **Cline** - Assistente de desenvolvimento
    * **Zed** - Editor colaborativo
    * **Continue** - Extensão de IA para VS Code/JetBrains
    * **Amp** - Agente de código autônomo

    **CLIs e Terminais:**

    * **Amazon Q CLI** - AWS AI assistant
    * **Gemini CLI** - Google AI no terminal
    * **goose** - CLI de IA de código aberto

    **Plataformas:**

    * **ChatGPT** - OpenAI (suporte MCP adicionado)
    * **Amazon Q Developer** - IDE plugin

    **Configuração Genérica:**

    Para clientes que usam configuração JSON:

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer SEU_TOKEN"
          ]
        }
      }
    }
    ```

    Para clientes que suportam HTTP direto:

    * **URL:** `https://brapi.dev/api/mcp/mcp`
    * **Header:** `Authorization: Bearer SEU_TOKEN`
  </Tab>
</Tabs>

## Ferramentas Disponíveis

O servidor MCP expõe 9 ferramentas para assistentes de IA:

### Ferramentas Públicas (Sem Autenticação)

| Ferramenta                          | Descrição                                                   |
| ----------------------------------- | ----------------------------------------------------------- |
| `get_available_stocks`              | Lista ações, FIIs, BDRs e índices com filtros (setor, tipo) |
| `get_available_currencies`          | Lista pares de moedas disponíveis (USD-BRL, EUR-BRL, etc.)  |
| `get_available_cryptocurrencies`    | Lista criptomoedas disponíveis (BTC, ETH, etc.)             |
| `get_available_inflation_countries` | Lista países com dados de inflação                          |

### Ferramentas Premium (Requer Token)

| Ferramenta            | Descrição                                     |
| --------------------- | --------------------------------------------- |
| `get_stock_quotes`    | Cotações e histórico de ações, FIIs, BDRs     |
| `get_currency_rates`  | Taxas de câmbio em tempo real                 |
| `get_crypto_prices`   | Preços de criptomoedas em BRL e outras moedas |
| `get_inflation_data`  | Dados de inflação (IPCA, IGPM)                |
| `get_prime_rate_data` | Taxa SELIC e histórico                        |

## Exemplos de Consultas

### Análise de Ações

```txt
Analise o desempenho da PETR4 no último mês e compare com VALE3
```

```txt
Quais são as 5 ações com maior volume de negociação hoje?
```

```txt
Liste todas as empresas do setor financeiro ordenadas por valor de mercado
```

### Câmbio e Criptomoedas

```txt
Qual é a cotação atual do dólar?
```

```txt
Compare o preço do Bitcoin e Ethereum em reais
```

### Indicadores Econômicos

```txt
Qual é a taxa SELIC atual e como ela evoluiu nos últimos 12 meses?
```

```txt
Mostre a inflação (IPCA) acumulada no ano
```

### Descoberta de Mercado

```txt
Liste os fundos imobiliários com maior volume
```

```txt
Quais BDRs estão disponíveis na B3?
```

## Filtros Avançados

A ferramenta `get_available_stocks` suporta filtros para consultas específicas:

**Por Setor:**

* `Finance` - Bancos e financeiras
* `Energy Minerals` - Petróleo e energia
* `Technology Services` - Tecnologia
* `Health Services` - Saúde
* `Retail Trade` - Varejo
* `Utilities` - Energia elétrica e saneamento

**Por Tipo:**

* `stock` - Ações ordinárias e preferenciais
* `fund` - Fundos imobiliários (FIIs)
* `bdr` - Brazilian Depositary Receipts

**Ordenação:**

* `volume` - Volume de negociação
* `market_cap_basic` - Valor de mercado
* `change` - Variação percentual
* `close` - Preço de fechamento
* `name` - Ordem alfabética

## Solução de Problemas

<Tabs items={['Conexão', 'Autenticação', 'Runtime']}>
  <Tab value="Conexão">
    ### Erros de Conexão

    **"Connection refused" ou "Network error"**

    1. Verifique sua conexão com a internet
    2. Confirme que a URL está correta: `https://brapi.dev/api/mcp/mcp`
    3. Teste a conexão manualmente:

    ```bash
    curl -I https://brapi.dev/api/mcp/mcp
    ```

    **Problemas de TLS/Certificado**

    Adicione a flag `--experimental-fetch`:

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "npx",
          "args": [
            "--node-options=--experimental-fetch",
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer SEU_TOKEN"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab value="Autenticação">
    ### Erros de Token

    **"Token de autenticação obrigatório" (TOKEN\_REQUIRED)**

    * Ferramentas premium requerem token válido
    * Verifique se o header Authorization está configurado corretamente
    * Formato correto: `Authorization: Bearer SEU_TOKEN`

    **"Token de API inválido ou expirado" (TOKEN\_INVALID)**

    1. Acesse o dashboard da Brapi
    2. Verifique se o token está ativo
    3. Regenere o token se necessário
    4. Certifique-se de não ter espaços extras

    **Ferramentas Públicas**

    As ferramentas `get_available_*` funcionam sem token para testes:

    ```txt
    Liste as ações disponíveis na B3
    ```
  </Tab>

  <Tab value="Runtime">
    ### Erros de Runtime

    **"ERR\_MODULE\_NOT\_FOUND"**

    Use `bunx` em vez de `npx`:

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "bunx",
          "args": [
            "mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer SEU_TOKEN"
          ]
        }
      }
    }
    ```

    **Alternativa com Deno:**

    ```json
    {
      "mcpServers": {
        "brapi": {
          "command": "deno",
          "args": [
            "run",
            "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION",
            "--allow-net",
            "npm:mcp-remote",
            "https://brapi.dev/api/mcp/mcp",
            "--header",
            "Authorization:Bearer SEU_TOKEN"
          ]
        }
      }
    }
    ```

    **Node.js Versão**

    Certifique-se de usar Node.js v18 ou superior:

    ```bash
    node --version
    ```
  </Tab>
</Tabs>

## Autenticação

O servidor MCP suporta os mesmos métodos de autenticação da API REST:

| Método          | Exemplo                               | Recomendado |
| --------------- | ------------------------------------- | ----------- |
| Header Bearer   | `Authorization: Bearer sua_chave_api` | Sim         |
| Header Simples  | `Authorization: sua_chave_api`        | Sim         |
| Query Parameter | `?token=sua_chave_api`                | Não         |

## Limites e Planos

As requisições MCP seguem os mesmos limites da API REST:

| Plano        | Requisições/mês | Ideal para                   |
| ------------ | --------------- | ---------------------------- |
| **Gratuito** | 15.000          | Testes e projetos pessoais   |
| **Startup**  | 150.000         | Startups e pequenas empresas |
| **Pro**      | 500.000         | Aplicações de alto volume    |

[Ver todos os planos](https://brapi.dev/pricing)

## Segurança

O servidor MCP implementa:

* Autenticação obrigatória para ferramentas premium
* Transmissão segura via HTTPS/TLS
* Validação de tokens a cada requisição
* Validação de parâmetros de entrada
* Rate limiting baseado no plano

## Clientes Compatíveis

O protocolo MCP é suportado por mais de 100 clientes. Os mais populares:

| Cliente        | Tipo              | Configuração         |
| -------------- | ----------------- | -------------------- |
| Claude Code    | CLI               | `claude mcp add`     |
| Claude Desktop | Desktop App       | JSON config          |
| Cursor         | IDE               | JSON config          |
| VS Code        | IDE               | JSON config          |
| Windsurf       | IDE               | JSON config          |
| n8n            | Automação         | MCP Client Tool node |
| Cline          | VS Code Extension | JSON config          |
| Continue       | IDE Extension     | JSON config          |
| Amazon Q       | CLI/IDE           | JSON config          |
| goose          | CLI               | JSON config          |

[Lista completa de clientes MCP](https://github.com/modelcontextprotocol/servers)

## Próximos Passos

<Cards>
  <Card title="Criar Conta" href="https://brapi.dev" />

  <Card title="Documentação da API" href="/docs" />

  <Card title="Exemplos de Integração" href="/docs/acoes-cotacao" />

  <Card title="Suporte" href="https://brapi.dev/contact" />
</Cards>

***

<Callout type="warn">
  **Aviso Legal**

  Os dados são fornecidos apenas para fins informativos e não constituem
  aconselhamento financeiro. Consulte sempre um profissional qualificado antes de
  tomar decisões de investimento.
</Callout>