> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP server
> Financial Data API's native Model Context Protocol server: read-only macro tools for Claude Code, Claude Desktop, and Cursor.
Financial Data API ships a native [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the public API as agent tools. Add it to Claude Code, Claude Desktop, or Cursor and your agent can query official-source macro indicators, rates, FX reference rates, the economic calendar, and derived analytics conversationally, with no glue code.
The server is read-only by design: every tool maps to a `GET` endpoint on the Financial Data API HTTP API and returns the raw JSON envelope as text, so the agent sees `data`, `meta`, and `requestId` and can follow `next_cursor` for pagination itself.
Transport is stdio. The server's `stdout` is reserved for the MCP protocol; it logs only to `stderr`. You do not need to interact with this directly, but it is why the server is launched as a long-running subprocess by your agent host.
## Read-only tools
| Tool | What it does |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `screen_macro` | Screen countries by macro indicator values using the `filter` DSL (`field:operator:value`, AND-ed). |
| `screen_equities` | Screen the scored US equity universe by valuation multiples, financial ratios, and price analytics using the same `filter` DSL. |
| `insider_trades` | SEC Forms 3/4/5 insider transactions for a company, by ticker, CIK, or entity id. Also available over REST as `GET /companies/{idOrLookup}/insider-trades`. |
| `institutional_holdings` | Quarterly SEC 13F holdings for 25 headline institutional filers, ticker- or filer-centric. |
| `get_latest_observations` | Get the latest public observation per canonical indicator, optionally scoped to one country. |
| `cross_country` | Cross-country macro differentials for a scope or country versus its peer basket. |
| `rates_analytics` | Rates analytics (real rate, curve spread, policy-cycle position) for a scope or country. |
| `observation_provenance` | The provenance (source, raw payload metadata, ingestion evidence) for a single observation by id. |
The server also exposes supporting tools: `list_indicators`, `list_countries`, `country_indicators`, `get_observations`, `screener_fields` (discover macro screener fields and operators), `equity_screener_fields` (discover equity screener fields and operators), `economic_calendar`, `official_events`, `source_health`, and `resolve_entity` (resolve a country, company, or instrument by alias such as a ticker or ISO code).
Tell your agent to call `screener_fields` before `screen_macro`, and `equity_screener_fields` before `screen_equities`. Each returns the screenable field slugs, the operators (`gt`, `lt`, `gte`, `lte`, `eq`, `in`), and the DSL syntax, so the agent builds a valid filter instead of guessing field names.
## Build the server
Build once to emit the runnable entry point at `mcp/dist/index.js`.
```bash npm theme={"theme":"css-variables"}
cd mcp
npm install
npm run build # emits dist/index.js
```
## Add it to your agent
Register the server with the `claude mcp add` command, passing your key via `--env` and the built entry point after the `--` separator. Use an absolute path.
```bash theme={"theme":"css-variables"}
claude mcp add financialdatapi \
--env FINANCIALDATA_API_KEY=your_key_here \
-- node /absolute/path/to/financialdatapi/mcp/dist/index.js
```
Everything after `--` is the launch command for the server. The `FINANCIALDATA_API_KEY` value is sent as `x-api-key` on every request.
Add a `financialdatapi` entry to the `mcpServers` block in `claude_desktop_config.json`, then restart Claude Desktop.
```json theme={"theme":"css-variables"}
{
"mcpServers": {
"financialdatapi": {
"command": "node",
"args": ["/absolute/path/to/financialdatapi/mcp/dist/index.js"],
"env": {
"FINANCIALDATA_API_BASE_URL": "https://api.financialdatapi.com",
"FINANCIALDATA_API_KEY": "your_key_here"
}
}
}
}
```
Add the same `mcpServers` block to `~/.cursor/mcp.json`.
```json theme={"theme":"css-variables"}
{
"mcpServers": {
"financialdatapi": {
"command": "node",
"args": ["/absolute/path/to/financialdatapi/mcp/dist/index.js"],
"env": {
"FINANCIALDATA_API_KEY": "your_key_here"
}
}
}
}
```
Ask your agent something macro and let it pick the tool, for example: "Which countries have CPI inflation above 3% and unemployment below 5%?" The agent will call `screener_fields`, then `screen_macro` with `filter=cpi_inflation_yoy:gt:3,unemployment_rate:lt:5`, and read the result envelope directly.
## Configuration
| Env var | Default | Notes |
| ---------------------------- | --------------------------------- | ------------------------------------------------------------ |
| `FINANCIALDATA_API_BASE_URL` | `https://api.financialdatapi.com` | Financial Data API base URL. |
| `FINANCIALDATA_API_KEY` | *(unset)* | Sent as `x-api-key` when present. Production requires a key. |
During development you can run the server without building it with `npm run dev` from the `mcp/` directory. It uses `tsx` and runs the TypeScript source directly. For agent hosts, prefer the built `dist/index.js`.
## How errors surface
Because each tool returns the raw HTTP result, an agent sees Financial Data API's stable error codes verbatim. A request that fails validation returns a `bad_request` body (for example, an unknown query parameter, which Financial Data API rejects rather than ignores), and a missing or insufficient key returns `unauthorized` or `forbidden`. The agent can read `error.code` and adjust, rather than retrying blindly.