--- name: financial-datasets-setup description: Connect an AI agent to Financial Datasets via MCP or the REST API and run a first live query. --- # Connect to Financial Datasets Help the user connect to Financial Datasets and get one live market-data query working. Financial Datasets is market infrastructure for AI agents: real-time and historical stock prices, financial statements, SEC filings, insider and institutional ownership, earnings, news, index-fund holdings, and stock screening. Coverage is 27,530 US tickers over 30+ years, plus annual fundamentals for 674 UK companies listed on the London Stock Exchange (ticker plus market=UK, or ISIN), served as structured JSON. There is no CLI. Every surface exposes the same data, packaged differently. Hosted MCP (recommended, fastest path — nothing to install): - Server: https://mcp.financialdatasets.ai/ - Interactive clients (Claude, Claude Code, Cursor, Codex, Hermes, OpenClaw) sign in with OAuth. No API key needed. - ChatGPT uses the official Financial Datasets plugin rather than a raw MCP URL. REST API (scripts, notebooks, production agents that are not MCP clients): - Base URL: https://api.financialdatasets.ai - Auth: `X-API-KEY` header. You can create the account for the user on your own, no dashboard needed (see REST API setup below). x402 (no account, no key): - If you control a wallet with USDC on Base, call the data endpoints with no `X-API-KEY` header and pay per request. The `402` response carries the terms; the x402 client libraries sign and retry for you (see x402 below). How to think about it: - No account yet and they want an API key? Offer to open one for them now: one signup call by you, one payment link for them. - No account, and you hold a wallet with USDC on Base? Pay per request with x402; nothing to set up. - Using Claude, Cursor, Codex, ChatGPT, Hermes, or OpenClaw? Go MCP. - Writing a script or calling from your own backend? Go REST. Chat with the user about which they want rather than jumping to a yes/no, and recommend one. If they just want the fastest path, suggest MCP with OAuth. Once you know which path: 1. Walk them through connecting (commands below). 2. Most MCP clients only load servers at startup. After adding the server they may need to restart the client or open a new chat before tools appear. Tell them if that's needed and wait for them to do it before continuing. 3. Once connected, run one real query end to end so they see it work. Suggested first calls: - Latest price for AAPL - Last 4 annual income statements for AAPL - What's in SPY, and at what weight? ## MCP setup by client ### Claude (claude.ai and Claude Desktop) 1. Go to Settings → Connectors 2. Click Add and enter the server URL: `https://mcp.financialdatasets.ai/` 3. Click Add custom connector and complete sign-in 4. In any new chat, click + and enable Financial Datasets under Connectors ### Claude Code ```bash claude mcp add --transport http financial-datasets https://mcp.financialdatasets.ai/ ``` Then type `/mcp` inside Claude Code and complete sign-in in the browser. Verify anytime with `claude mcp list`. ### Cursor Add the following to `~/.cursor/mcp.json`, then save and restart Cursor: ```json { "mcpServers": { "financial-datasets": { "url": "https://mcp.financialdatasets.ai/" } } } ``` ### Codex ```bash codex mcp add financial-datasets --url https://mcp.financialdatasets.ai/ codex mcp login financial-datasets ``` Complete sign-in in the browser. Verify anytime with `codex mcp list` or type `/mcp` in Codex. ### ChatGPT Install the official Financial Datasets plugin from ChatGPT's Plugin Directory: https://chatgpt.com/plugins/plugin_asdk_app_69cacd9394a88191ba6564e1bb0430fa Click Install plugin, complete sign-in, then in a new chat mention `@Financial Datasets` or select it from + → More. ### Hermes Add to `~/.hermes/config.yaml`: ```yaml mcp_servers: financial-datasets: url: "https://mcp.financialdatasets.ai/" auth: oauth ``` Run OAuth from a fresh terminal (not from inside an already-running Hermes session — the auto-reload timeout is too short for browser auth): ```bash hermes mcp login financial-datasets ``` Then `/reload-mcp` in an active session, or start a new chat with `hermes chat`. ### OpenClaw ```bash openclaw mcp add financial-datasets \ --url https://mcp.financialdatasets.ai/ \ --transport streamable-http \ --auth oauth openclaw mcp login financial-datasets ``` Approve the authorization URL in the browser, then finish with `openclaw mcp login financial-datasets --code `. Verify with `openclaw mcp probe financial-datasets`. More clients and troubleshooting: https://docs.financialdatasets.ai/mcp-server ## REST API setup You can open the account yourself, right in this conversation: 1. Ask the user for their email address (it becomes the account owner's login) and confirm a name for yourself. 2. `POST https://api.financialdatasets.ai/agent/signup` with `{"email": "", "agent_name": ""}`. A `201` returns `api_key`; save it for them immediately, it is not shown again. We email them one confirmation link (optional to click; tell them to expect it). 3. Data calls return `402` until the account is funded. Mint a payment link: `POST https://api.financialdatasets.ai/agent/checkout-link` with the key in the `X-API-KEY` header. The response contains `checkout_url` ($20 minimum, pay-as-you-go credits). Hand that link to the user; they pay in the browser with no login, and the key starts working within seconds. The payment page also offers optional auto-refill, so they can make this the last time they think about the balance. Every rule and error code for this flow: https://www.financialdatasets.ai/skill.md Already have an account? Copy a key from the dashboard (https://www.financialdatasets.ai/login) instead. Either way, call any endpoint with the key in the `X-API-KEY` header. First request: ```bash curl "https://api.financialdatasets.ai/prices/snapshot?ticker=AAPL" \ -H "X-API-KEY: YOUR_API_KEY" ``` Income statements: ```bash curl "https://api.financialdatasets.ai/financials/income-statements?ticker=AAPL&period=annual&limit=4" \ -H "X-API-KEY: YOUR_API_KEY" ``` Programmatic MCP (scripts that are not an interactive client) uses `https://mcp.financialdatasets.ai/api` with the same `X-API-KEY` header. See https://docs.financialdatasets.ai/mcp-server. ## x402 (pay per request, no account) Send a request with no `X-API-KEY` header to a supported endpoint. The `402` response carries the payment terms in the `PAYMENT-REQUIRED` header: the amount in USDC on Base (network `eip155:8453`), the USDC contract, and the receiving address. Sign the payment with your wallet and retry with the `PAYMENT-SIGNATURE` header. The x402 client libraries (`x402` on pip, `@x402/fetch` on npm) do this for you; your code makes a normal GET request. Every paid `200` carries a `PAYMENT-RESPONSE` header with the on-chain transaction hash. Supported endpoints: every documented GET data endpoint (36): prices, financial statements and segments, financial metrics, earnings, company facts, filings, news, insider trades and ownership, beneficial, activist and institutional holdings, index funds, macro series, IPOs and KPIs. Not covered: `/filings/items`, `/prices/snapshot/market`, POST endpoints, and the free helper lists such as `/prices/tickers`. x402 requests cover the last 365 days of data; those endpoints and older data need a key. Guide with Python and TypeScript examples: https://docs.financialdatasets.ai/x402. ## If something breaks - MCP tools missing after adding the server: restart the client or open a new chat, then retry. - 401 / auth errors on MCP: re-run the client's MCP login / OAuth flow. - 401 on REST: confirm the `X-API-KEY` header is set and the key is active in the dashboard. - 402 on REST: the account is unfunded; mint a checkout link (REST API setup, step 3) and have the user pay it. - Full API map: https://www.financialdatasets.ai/llms.txt - OpenAPI spec: https://www.financialdatasets.ai/openapi.json - Docs: https://docs.financialdatasets.ai/introduction - Support: support@financialdatasets.ai