Financial Data API — Documentation

Financial Data API ships a native Model Context Protocol 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.

cd mcp
npm install
npm run build   # emits dist/index.js

Add it to your agent

Add to Claude Code

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.

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 to Claude Desktop

Add a financialdatapi entry to the mcpServers block in claude_desktop_config.json, then restart Claude Desktop.

{
  "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 to Cursor

Add the same mcpServers block to ~/.cursor/mcp.json.

{
  "mcpServers": {
    "financialdatapi": {
      "command": "node",
      "args": ["/absolute/path/to/financialdatapi/mcp/dist/index.js"],
      "env": {
        "FINANCIALDATA_API_KEY": "your_key_here"
      }
    }
  }
}

Try a prompt

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.

Get started

Data products

Data infrastructure

Agent access

Resources

Legal

MCP server

Read-only tools

Build the server

Add it to your agent

Configuration

How errors surface

​Read-only tools

​Build the server

​Add it to your agent

​Configuration

​How errors surface

Read-only tools

Build the server

Add it to your agent

Configuration

How errors surface