DFin MCP
The DFin MCP surface exposes selected public API v1 capabilities for agents, including filing search, securities search, screening, financials, stock context, and fund analytics. Use this page for MCP-specific workflow guidance, and use the API v1 reference for detailed parameter and response contracts.
1.0 Overview
| Runtime endpoint | /mcp |
|---|---|
| MCP docs resource | dfin://docs/mcp |
| API reference | /docs/api/v1/ |
| API docs resource | dfin://docs/api/v1 |
| Agent hints resource | dfin://docs/api/v1/agent-hints |
MCP docs are intentionally unversioned for now. Tool names, argument schemas, and return shapes should be treated as a public contract.
2.0 Authentication
Data tools use the same public API key model as REST. Send the API key in the Authorization header as Authorization: Bearer <api_key>. Documentation resources are public so agents can inspect the contract before calling data tools.
3.0 Tool Reference
Use this table to choose the right public MCP tool. Detailed argument and response contracts are linked from the API v1 reference.
| Area | Tool | Purpose | Guidance |
|---|---|---|---|
| Filing search | search_filings |
Search structured company filings with up to 12 natural-language queries; optionally narrow by ticker, fiscal period, fiscal year, filing type, and search type. | Use for source-text evidence from structured company filings. |
| Securities search | search_securities |
Look up stocks or ETFs by name or ticker; use search_filings instead when the user needs SEC filing text or source evidence. | Use for focused stock or ETF lookup; defaults to U.S. stock search. |
| Screener | get_screener_options |
Return the current public screener contract; use this as the source of truth for filters, option values, sort fields, output fields, result formats, and mode membership. | Call before constructing any non-trivial screener request. |
| Screener | run_screener_basic |
Run a basic stock screen; call get_screener_options(mode="basic") first and use only filters listed in options.modes.basic. | Use only when every selected filter appears in options.modes.basic. |
| Screener | run_screener_advanced |
Run an advanced stock screen; call get_screener_options(mode="all") first and use options.modes.advanced for advanced filters. | Use for advanced-only filter families and rules. |
| Financials | get_financial_single_statement |
Return one financial statement for a ticker and fiscal year. Use canonical statement names income_statement, balance_sheet, or cash_flow. Current public data supports period="FY" only. format must be field_map or rows; do not use json. | Use for one exact fiscal year and statement family. |
| Financials | get_financial_stitched_statements |
Return latest-N financial statement time series. Use canonical statement names income_statement, balance_sheet, or cash_flow. Current public data supports period_type="annual" only. format must be field_map or rows; do not use json. | Use for latest-N statement time series. |
| Financials | get_financial_ratios |
Return annual FY financial ratios for one ticker.exchange stock ticker and fiscal year from 2000 through 2050; optional fields accepts canonical camelCase ratio keys such as returnOnEquity or grossProfitMargin. | Use for annual FY ratio metrics. |
| Stock context | get_stock_context |
Call this first when the user wants to discuss a specific stock in detail; requires ticker in ticker.exchange format, for example MSFT.US or BRK-B.US. If the user gave a company name or bare/ambiguous symbol, call search_securities first and pass the resolved ticker. Use financial statement and ratio tools for exact financial data. | Call first for detailed discussion of one specific stock; ticker format is ticker.exchange, for example MSFT.US. |
| Fund analytics | get_fund_movers |
Return cached fund movers for one fund ticker; omit delta for daily movers or use a period such as mtd, 52w, or 3y. | Returns cached public fund movers and may report a processing status. |
| Fund analytics | get_fund_highlow |
Return cached fund high/low analytics for one fund ticker; delta is required and margin is optional. | Returns cached public fund high/low analytics and may report a processing status. |
4.0 Recommended Flow
| Step | Detail |
|---|---|
| Inspect the MCP docs | Use dfin://docs/mcp for MCP-specific usage guidance and dfin://docs/api/v1 for detailed API v1 contracts. |
| Authenticate data tools | Send the public API key in the Authorization header as Bearer <api_key>. |
| Discover screener contracts | Call get_screener_options before constructing screener payloads. |
| Choose context tools early | Call get_stock_context first when the user wants to discuss one specific stock in detail. |
For screeners, call get_screener_options first and use the returned contract metadata. For detailed discussion of one stock, call get_stock_context first. Tickers should use ticker.exchange format, for example MSFT.US.
5.0 Resources
| Resource | Purpose |
|---|---|
dfin://docs/mcp | MCP-specific usage guidance for the public DFin MCP surface. |
dfin://docs/api/v1 | Detailed parameter and response contracts for public API v1 capabilities. |
dfin://docs/api/v1/agent-hints | Compact endpoint and tool signposts for agents. |
6.0 Response Notes
Most tools return the public data payload directly. Proxy-backed or status-aware tools return {"status_code": <int>, "data": <payload>}. A 202 status means the requested cached data may still be preparing.
