MCP (Model Context Protocol)

O Model Context Protocol (MCP) permite que modelos de linguagem acessem a Partnr API diretamente, facilitando a integração com agentes de IA e assistentes inteligentes.

O servidor MCP da Partnr utiliza o modo streamable (HTTP + SSE). O cliente estabelece uma conexão HTTP com o endpoint e a comunicação ocorre via Server-Sent Events (SSE), em que mensagens JSON são enviados em stream. Esse modo é compatível com clientes MCP que suportam streamable (por exemplo: Claude Desktop, Cursor, Windsurf, Continue.dev, Cline).

Com o MCP da Partnr, você pode:

• Consultar dados de empresas, cotações e indicadores via linguagem natural
• Integrar com clientes MCP compatíveis com streamable (HTTP + SSE)
• Automatizar análises financeiras com agentes de IA

URL do Servidor MCP

https://mcp.partnr.ai/mcp

Segurança

Nunca exponha sua API key em repositórios públicos ou código client-side. Use variáveis de ambiente sempre que possível.

Autenticação

A autenticação é feita via header Authorization usando Bearer token:

Authorization: Bearer SUA_API_KEY

Configuração por Cliente

Claude Desktop

Adicione ao seu arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "partnr": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.partnr.ai/mcp",
        "--header",
        "Authorization:Bearer SUA_API_KEY"
      ]
    }
  }
}

Localização do arquivo:

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

Após salvar, reinicie o Claude Desktop.

Cursor

Adicione ao seu arquivo .cursor/mcp.json na raiz do projeto ou globalmente em ~/.cursor/mcp.json:

{
  "mcpServers": {
    "partnr": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.partnr.ai/mcp",
        "--header",
        "Authorization:Bearer ${PARTNR_API_KEY}"
      ],
      "env": {
        "PARTNR_API_KEY": "SUA_API_KEY"     
    }
  }
}

O Cursor detectará automaticamente o servidor MCP.

Windsurf

Adicione ao arquivo de configuração MCP do Windsurf (~/.windsurf/mcp.json):

{
  "mcpServers": {
    "partnr": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.partnr.ai/mcp",
        "--header",
        "Authorization:Bearer SUA_API_KEY"
      ]
    }
  }
}

Continue.dev

Adicione ao seu config.json do Continue:

{
  "mcpServers": [
    {
      "name": "partnr",
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.partnr.ai/mcp",
        "--header",
        "Authorization:Bearer SUA_API_KEY"
      ]
    }
  ]
}

Cline (VS Code)

No VS Code com Cline, adicione nas configurações do MCP:

{
  "mcpServers": {
    "partnr": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.partnr.ai/mcp",
        "--header",
        "Authorization:Bearer SUA_API_KEY"
      ]
    }
  }
}

Usando Variáveis de Ambiente

Para maior segurança, use variáveis de ambiente em vez de expor a API key diretamente:

Bash/Zsh

export PARTNR_API_KEY="SUA_API_KEY"

Configuração com variável

Suporte a variáveis

Nem todos os clientes MCP suportam substituição de variáveis de ambiente. Consulte a documentação do seu cliente específico. Se a variável não for expandida, substitua manualmente por SUA_API_KEY.

{
  "mcpServers": {
    "partnr": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.partnr.ai/mcp",
        "--header",
        "Authorization:Bearer ${PARTNR_API_KEY}"
      ]
    }
  }
}

Tools Disponíveis

O MCP da Partnr expõe as seguintes ferramentas:

Empresas

Tool	Descrição
companies_list	Lista todas as empresas disponíveis
companies_retrieve	Consulta detalhes de uma empresa específica
companies_ratios	Indicadores financeiros (ratios) de uma empresa
companies_valuationRatios	Indicadores de valuation de uma empresa
companies_reports	Relatórios padronizados (Balanço, DRE, DFC)
companies_rawReports	Relatórios brutos conforme CVM
companies_sharesHistory	Histórico de ações da empresa
companies_bankData	Dados bancários (para instituições financeiras)
companies_insiderTransactions	Transações de insiders
companies_cashCorporateActionsByCompany	Proventos de uma empresa
companies_cashCorporateActionsAll	Proventos de todas as empresas

Cotações

Tool	Descrição
stocks_quotes	Cotações históricas de um ticker

Notícias

Tool	Descrição
news_list	Lista artigos de notícias
news_retrieve	Consulta um artigo específico

Macroeconomia

Tool	Descrição
macro_listIndicators	Lista indicadores macroeconômicos
macro_retrieveIndicator	Consulta série temporal de um indicador

Screener

Tool	Descrição
screener_search	Filtra e ranqueia empresas por critérios

Utilitários

Tool	Descrição
search	Busca semântica em dados financeiros
fetch	Requisição HTTP genérica

Exemplos de Uso

Exemplo 1: Consultar dados de uma empresa

Prompt:

"Quais são os principais indicadores financeiros da Petrobras?"

O modelo usará automaticamente companies_ratios com o identificador PETR ou PETR3.

Exemplo 2: Analisar cotações

Prompt:

"Me mostre a evolução do preço de VALE3 nos últimos 6 meses"

O modelo usará stocks_quotes com os parâmetros de data apropriados.

Exemplo 3: Buscar notícias

Prompt:

"Quais são as últimas notícias sobre o setor bancário?"

O modelo usará news_list e filtrará por entidades do setor.

Exemplo 4: Screener de ações

Prompt:

"Liste as 10 ações com menor P/L do mercado brasileiro"

O modelo usará screener_search com filtros de droplet:PRICE_TO_EARNINGS.

Exemplo 5: Dados macroeconômicos

Prompt:

"Qual a taxa de inflação do Brasil nos últimos 12 meses?"

O modelo usará macro_retrieveIndicator com INFLATION_RATE.

Solução de problemas

Checklist rápido

Antes de aprofundar, confira:

1. URL exata: https://mcp.partnr.ai/mcp (sem barra no final).
2. API key: sem espaços, aspas ou quebras de linha; use variável de ambiente se o cliente suportar.
3. Header: Authorization: Bearer SUA_API_KEY (ou o formato exigido pelo adaptador).
4. JSON válido: sem vírgula após o último item, aspas duplas em chaves e valores.
5. Reinício: após alterar configuração, feche e reabra o cliente (Cursor/Claude/Windsurf).

"Connection refused" / "Failed to connect" / "ECONNREFUSED"

Causa: Cliente não alcança o servidor (rede, firewall, URL errada).

O que fazer:

1. Testar conectividade:

   curl -s -o /dev/null -w "%{http_code}" "https://mcp.partnr.ai/mcp"

   Resposta esperada: 405 (Method Not Allowed) — o endpoint existe e aceita apenas POST/SSE, não GET. Se der 401, a key chegou mas é inválida.

2. Em rede corporativa/VPN, verificar se mcp.partnr.ai e HTTPS (443) não estão bloqueados.

3. Confirmar que não está usando http:// nem URL com typo (ex.: partnr.com em vez de partnr.ai).

"401 Unauthorized"

Causa: API key ausente, inválida ou mal formatada na URL.

O que fazer:

1. Copiar a key de novo do painel Partnr (sem espaço no início/fim).
2. Se a key estiver em variável de ambiente, testar no terminal: echo $PARTNR_API_KEY (ou equivalente) e usar o mesmo valor na URL ao testar com curl.
3. Confirmar o header:

Authorization: Bearer SUA_API_KEY

4. Se estiver usando variável de ambiente, testar no terminal:

echo $PARTNR_API_KEY

5. Nova key em partnr.ai/contato se a atual tiver sido revogada.

"Tool not found" / Tools não aparecem

Causa: Cliente não listou as tools do servidor (config errada, cache, cliente não suporta streamable).

O que fazer:

1. Confirmar se está usando command: "npx" + mcp-remote (streamable).
2. Fechar o app por completo e reabrir; alguns clientes só recarregam o MCP ao iniciar.
3. Se o cliente exigir stdio em vez de streamable/SSE, ele não é compatível com este servidor.

Respostas lentas ou timeout

Causa: Consultas amplas (muitos tickers, período longo) ou rede lenta.

O que fazer:

1. Reduzir período em cotações (ex.: 3–6 meses em vez de anos).
2. Usar limit em listagens (empresas, notícias, etc.).
3. Fazer perguntas mais específicas para o modelo usar filtros (datas, tickers).

Limitações

• Rate limiting: O MCP segue os limites de acordo com o plano. Consulte os limites
• Timeout: Consultas muito complexas podem exceder o timeout do cliente
• Contexto: O modelo precisa de contexto suficiente para escolher a tool correta

Suporte

Está com problemas? Fale com um especialista ou envie um e-mail para [email protected].