# Set up the Belfort Data API (for AI agents)

> One page an AI agent reads to add the Belfort Data API to the app it runs in, test it, and tell its user what needs a sign-in.

You are an AI agent. Your user asked you to set up the Belfort Data API. It serves company figures
taken only from official filings, and every figure links to the filing it came from: U.S. SEC filings,
and filings in Japan, Europe, Korea, Taiwan and Brazil (see Markets below). Follow the steps for the app
you are running in, test it, then tell your user what you found.

## Rules

- Never ask your user to paste an API key into the conversation. Never print, log or store a key in a
  file that is shared or committed.
- You do not need a key to set this up. Ten U.S. companies answer with no key and no sign-in: AAPL, MSFT,
  JPM, KO, XOM, NVDA, AMZN, GOOGL, TSLA and LLY (Form 13F holdings by manager are charged even for
  these). Four companies in each of Japan, Europe, Korea and Taiwan do too (listed under Markets).
  Brazil has none.
- For any other company, the server asks for a sign-in: the user enters their email and a 6-digit code
  in their browser, at auth.belfortagent.xyz. Their app starts this when a tool needs it.
- A user who prefers a key creates one themselves at https://data.belfortagent.xyz/dashboard and puts it
  in the `BELFORT_API_KEY` environment variable. You read it from there.

MCP server: `https://api.belfortagent.xyz/mcp` (Streamable HTTP). REST base URL:
`https://api.belfortagent.xyz`.

## Markets

| Market | MCP tools | Free with no sign-in | Limits |
|---|---|---|---|
| U.S. (SEC) | `get_company`, `get_metrics`, `get_financials` and others | the ten above | — |
| Japan (EDINET) | `get_jp_company`, `get_jp_financials` | `7974` Nintendo, `6501` Hitachi, `8035` Tokyo Electron, `6861` Keyence | Full-year and half-year figures only since April 2024 |
| Europe (ESEF annual reports) | `get_eu_company`, `get_eu_financials`, `get_eu_filings` | At least one in each of the 16 countries covered, for example ASML `724500Y6DUVHQD6OXN27` and HSBC `MLU0ZO3ML4LN2LL2TL39`; the full list is on the [MCP page](/mcp/) | Annual only; 16 countries, not Germany, Ireland or Italy; look a company up by LEI |
| Korea (DART) | `get_kr_company`, `get_kr_financials` | `000660` SK hynix, `005380` Hyundai Motor, `035420` NAVER, `000270` Kia | Shallow history, from fiscal 2025 |
| Taiwan (TWSE and TPEx open data) | `get_tw_company`, `get_tw_financials`, `get_tw_monthly_revenue` | `2317` Hon Hai, `2454` MediaTek, `2308` Delta Electronics, `2412` Chunghwa Telecom | Shallow history, from 2026; income figures are year to date |
| Brazil (CVM) | `get_br_company`, `get_br_financials` | none | Paid accounts only |

The free companies share one hourly limit per network. REST routes are `/v1/jp/…`, `/v1/eu/…`,
`/v1/kr/…`, `/v1/tw/…` and `/v1/br/…`.

## 0. Check that you can reach it

Fetch `https://api.belfortagent.xyz/?ref=agent-setup` with a plain GET. It answers 200 with the API's front page.
If it fails, your app has no internet access here: tell your user, and stop.

## 1. Add it to the app you are running in

### Claude Code

```bash
claude mcp add --transport http belfort-data --scope user https://api.belfortagent.xyz/mcp
claude mcp list
```

`--scope user` makes it available in every project; leave it out for this project only. `claude mcp
list` shows `belfort-data` as connected. To go beyond the free companies, the user runs `/mcp` in Claude
Code, picks `belfort-data` and signs in in the browser.

### Claude (claude.ai, Claude Desktop, Claude mobile)

You cannot add a connector yourself here. Tell your user to:

1. Open Customize, then Connectors, choose + and then Add custom connector.
2. Name it Belfort Research Data and enter `https://api.belfortagent.xyz/mcp`.
3. Under Authentication choose Sign in when needed; under OAuth client choose Use Claude's published
   identity. Choose Add.

Then ask a question about one of the free companies in a new chat.

### Cursor

Add this server to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (this project). Merge it
into the existing `mcpServers` object; do not remove other servers.

```json
{
  "mcpServers": {
    "belfort-data": { "url": "https://api.belfortagent.xyz/mcp" }
  }
}
```

Cursor signs the user in when a tool needs it. A user with a key can add
`"headers": { "X-API-Key": "${env:BELFORT_API_KEY}" }` instead.

### Codex (CLI and IDE extension)

```bash
codex mcp add belfort-data --url https://api.belfortagent.xyz/mcp
```

or add to `~/.codex/config.toml`:

```toml
[mcp_servers.belfort-data]
url = "https://api.belfortagent.xyz/mcp"
```

To go beyond the free companies, the user runs `codex mcp login belfort-data`. A user with a key can set
`env_http_headers = { "X-API-Key" = "BELFORT_API_KEY" }` in the same block.

### Any other MCP client

Connect to `https://api.belfortagent.xyz/mcp` over Streamable HTTP. Sign in when the client asks, or
send the header `X-API-Key` read from `BELFORT_API_KEY`.

### No MCP: call the REST API

```bash
curl https://api.belfortagent.xyz/v1/companies/AAPL/metrics
```

For other companies send `X-API-Key: $BELFORT_API_KEY`, or pay per call with x402 if you hold a wallet
with USDC on Base: the API answers `402` with the price, and you pay and repeat the request. The full
reference is https://docs.belfortagent.xyz/llms.txt.

## 2. Test it

Ask for Apple's revenue: the MCP tool `get_metrics` with `id` `AAPL`, or the curl above. The answer has
`metric`, `value`, `period_end` and `source.filing_url`. Pick the newest annual revenue.

If your user cares about another market, also try one of its free companies, for example
`get_jp_financials` with `id` `7974` and `field` `revenue`.

## 3. Tell your user

Say, in your own words:

- Belfort is set up in this app, and you read Apple's newest annual revenue from its 10-K (give the
  figure, the period and the filing link).
- The free companies (ten in the U.S., four each in Japan, Europe, Korea and Taiwan) need nothing more.
  Brazil needs a paid account.
- For any other company they will be asked to sign in once with their email, or they can create a key
  at https://data.belfortagent.xyz/dashboard and set `BELFORT_API_KEY` themselves. They should never
  paste a key into this chat.

---
Source: https://docs.belfortagent.xyz/agent-setup/
