# Mercado Financeiro BR — how to use (mcp.ai)

Brazilian financial market data (B3): quotes, fundamentals, dividends, REITs (FIIs), BDRs, crypto, FX and macro indicators (Selic, inflation). Platform-hosted, no credentials, monthly subscription.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_mercado?ms=1781685480000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `mercado_crypto`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/mercado`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/mercado/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/mercado/crypto` — Cotação de criptomoedas (BTC, ETH, …) na moeda escolhida (BRL por padrão). Cobrado por request.
  - body: { coins: string[], currency?: string }
- `POST https://api.mcp.ai/api/mercado/currency` — Câmbio entre pares de moedas (ex.: USD-BRL, EUR-BRL). Cobrado por request.
  - body: { pairs: string[] }
- `POST https://api.mcp.ai/api/mercado/list` — Lista/screener de ativos da B3 (ações, FIIs, BDRs) com busca, filtro por tipo/setor e ordenação (ex.: por variação, volume ou market cap). Cobrado por request.
  - body: { search?: string, type?: string, sector?: string, sort_by?: string, sort_order?: string, limit?: integer }
- `POST https://api.mcp.ai/api/mercado/macro` — Indicadores macroeconômicos brasileiros: prime_rate (Selic/juros) ou inflation (IPCA), com opção de série histórica. Cobrado por request.
  - body: { indicator: string, country?: string, historical?: boolean, start?: string, end?: string }
- `POST https://api.mcp.ai/api/mercado/quote` — Cotação de ações, FIIs e BDRs da B3 em lote (até 20 tickers numa chamada), com opção de dados fundamentalistas (via modules: balanceSheetHistory, incomeStatementHistory, cashflowHistory, etc.), divide
  - body: { tickers: string[], range?: string, interval?: string, fundamental?: boolean, dividends?: boolean, modules?: string[] }
- `POST https://api.mcp.ai/api/mercado/search/ticker` — Resolve o código (ticker) de um ativo a partir de um trecho do nome/código. Discovery rápido; NÃO é cobrado.
  - body: { query: string }

## Example prompts
- "Quote and P/E for PETR4, VALE3 and ITUB4"
- "Compare the dividend yield of HGLG11 and KNRI11"
- "What are the latest Selic rate and IPCA inflation?"

## More
- Page: https://mcp.ai/mercado
- Agent spec (llms.txt): https://mcp.ai/mercado/llms.txt
- Postman collection: https://mcp.ai/mercado/postman.json