--- name: finks-api description: | Connect, authenticate and use Finks API for financial news, SEC filings, earnings call transcripts, market data and US company screening. Use when the user wants financial context inside a coding agent, wants Finks available through MCP, or wants to add Finks API to application code. Reuse an existing key first, prefer MCP sign-in over a pasted key, and verify with a real call before declaring setup complete. --- # Finks API Financial context for AI agents: search news, filings and market data by meaning, read the whole record behind a result, and screen US companies. ## Pick the path | Job | Path | | --- | --- | | The agent needs financial data in this session | MCP (step 3a) | | The user's code will call Finks after this session ends | REST (step 3b) | ## Setup Run the steps in order: preflight, install, connect, verify, hand off. Do every step the terminal can do; stop for the user only at browser sign-in or to fetch a key. ### 1. Preflight 1. If `FINKS_API_KEY` is set, check it without printing it: ```bash curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $FINKS_API_KEY" https://data.finks.ai/v1/account ``` `200` means reuse it (this call is not metered). `401` means the key is revoked or wrong: ask the user for a new one. Never replace a working key. 2. Check whether this agent already has a `finks-api` MCP server (`claude mcp list`, `codex mcp list`, or the client's MCP settings) pointing at the URL in step 3a. If it is connected and the `finks_*` tools are in your tool list, go to step 4. Another server named `finks` may be an internal Finks tool, not this API: leave it alone. ### 2. Install this skill Save this file where the agent loads skills, so later sessions use it without being told. Overwrite an older copy. | Agent | Command | | --- | --- | | Claude Code | `mkdir -p ~/.claude/skills/finks-api && curl -fsSL https://finks.ai/SKILL.md -o ~/.claude/skills/finks-api/SKILL.md` | | Codex, Cursor and other Agent Skills clients | `mkdir -p ~/.agents/skills/finks-api && curl -fsSL https://finks.ai/SKILL.md -o ~/.agents/skills/finks-api/SKILL.md` | ### 3a. Connect MCP The server is `https://mcp.data.finks.ai/mcp` (streamable HTTP, 11 read-only tools). Sign-in (OAuth) needs no key and works in clients that support Client ID Metadata Documents: Claude Code, Codex, Hermes, and the Claude, ChatGPT and Grok apps. Every other client connects with a key. **Claude Code: sign in** 1. You run (user scope, so it works in every folder and session): ```bash claude mcp add --transport http --scope user finks-api https://mcp.data.finks.ai/mcp ``` 2. The user signs in. `/mcp` is the user's command, so you cannot run it, and it needs an interactive terminal: in the Claude desktop app, tell them to open a terminal and run `claude` first. Tell them: type `/mcp`, pick `finks-api`, choose **Authenticate**, then sign in in the browser (Google, GitHub or an email link) and approve. Wait for them to say it is done; waiting is not an error. 3. Check it took: `claude mcp get finks-api` no longer says it needs authentication. If it still does, ask the user what the browser showed at the end of sign-in. **Codex: sign in** 1. You run both; the second opens the browser for the user to sign in and approve. Wait for it to finish. ```bash codex mcp add finks-api --url https://mcp.data.finks.ai/mcp codex mcp login finks-api ``` **Hermes: sign in** 1. Add this to `~/.hermes/config.yaml` (if it already has `mcp_servers`, add the `finks-api` entry under it). Hermes signs in with Finks' Client ID Metadata Document; no key. ```yaml mcp_servers: finks-api: url: https://mcp.data.finks.ai/mcp auth: oauth ``` 2. Run `hermes mcp login finks-api`; the browser opens for the user to sign in and approve. Then run `/reload-mcp` in Hermes. **Claude (web, desktop, mobile), ChatGPT and Grok:** set up in the app, not the terminal. Tell the user: add a custom connector with the URL above and OAuth, then sign in. ChatGPT needs developer mode on first; Grok's is at grok.com/connectors, New Connector, Custom. **After sign-in:** a server added during a session may not show its tools until it reconnects. If the `finks_*` tools are not in your tool list, ask the user to start a new session; the skill installed in step 2 picks setup back up at step 4. Each app connected by sign-in gets its own key, named `MCP: `, which the user can revoke at https://dashboard.finks.ai/keys. **Any other client: connect with a key.** Get a key first (step 3b, item 1). Each config reads `FINKS_API_KEY` from the client's own environment at run time, not a project `.env`: have the user export it in their shell profile, then fully restart the client. Never write the key itself into a config or a command. - **Cursor** (~/.cursor/mcp.json): Add to the file. Reads FINKS_API_KEY from your environment. ```json { "mcpServers": { "finks-api": { "url": "https://mcp.data.finks.ai/mcp", "headers": { "Authorization": "Bearer ${env:FINKS_API_KEY}" } } } } ``` - **VS Code** (.vscode/mcp.json): Add to the file. VS Code asks for your key once. ```json { "inputs": [ { "type": "promptString", "id": "finks-api-key", "description": "Finks API key", "password": true } ], "servers": { "finks-api": { "type": "http", "url": "https://mcp.data.finks.ai/mcp", "headers": { "Authorization": "Bearer ${input:finks-api-key}" } } } } ``` - **Gemini CLI** (Terminal): Run once in your terminal. Gemini CLI reads FINKS_API_KEY from your environment when it loads. ```bash gemini mcp add --scope user --transport http \ --header 'Authorization: Bearer ${FINKS_API_KEY}' \ finks-api https://mcp.data.finks.ai/mcp ``` ### 3b. Connect REST 1. If there is no key, the user signs in at https://dashboard.finks.ai/signin (a free account comes with a key) and copies it from https://dashboard.finks.ai/keys. This is the one manual step. 2. Put it in the environment or the project's `.env` as `FINKS_API_KEY`, and confirm `.env` is gitignored. Never put it in code, a command line or a log. ### 4. Verify Setup is complete only when a search returns results. - **MCP:** call `finks_account`, then `finks_search` with the query below. - **REST:** ```bash curl -sS "https://data.finks.ai/v1/search" \ -H "Authorization: Bearer $FINKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Nvidia short interest, holders and insider selling", "limit": 10, "symbols": [ "NVDA" ] }' # Next page: the same body plus "cursor": , while "has_more" is true. ``` ### 5. Hand off End your last reply with what the user does next, in plain words, then these prompts as a list, word for word: - If the `finks_*` tools are not loaded in this session yet: "Start a new chat, then try one of these:" - If they are: "Finks is ready. Try one of these:", and offer to run the first one now. 1. Write me an investment report on NVIDIA. 2. Which banks beat earnings last quarter and pay a dividend over 3%? 3. What's moving the market today? In a later session, when the user asks one of these and the `finks_*` tools are loaded, answer it with them: the answer is the verify step. ## Tools The MCP tools, and the route each one calls for REST. | Tool | Route | Use it for | | --- | --- | --- | | `finks_search` | `POST /v1/search` | Search briefs, articles, filings and earnings call transcripts with the same filters as the API. Its input schema is the live tool schema. | | `finks_get_content` | `GET /v1/content/{id}` | The whole record behind any result id. | | `finks_list_filing_events` | `GET /v1/content` | Filing events, newest first, after a summary header; filings sent together stay together. Page back with `older`. | | `finks_account` | `GET /v1/account` | Your account, plan limits, usage and masked keys. Not metered. | | `finks_account_usage` | `GET /v1/account/usage` | Usage for one month, the current UTC month by default. Not metered. | | `finks_search_fields` | `GET /v1/search/fields` | The search catalog and the result fields your key can see. Not metered. | | `finks_screener` | `POST /v1/screener` | Screen listed companies with a normalized query or in plain words. | | `finks_screener_fields` | `GET /v1/screener/fields` | The screener's fields, operators, units and values. Not metered. | | `finks_get_event` | `GET /v1/events/{ledger_event_id}` | One filing event by its ledger id. | | `finks_datasets` | `GET /v1/datasets` | Every dataset Finks serves, with its routes and source, and whether your plan includes it. Not metered. | | `finks_latest_filings` | `GET /v1/companies/{symbol}/events?types=filing` | A company's newest SEC filings, newest first. | ## Rules - Base URL: https://data.finks.ai. Every route answers JSON. - Auth: send `Authorization: Bearer $FINKS_API_KEY` on every request. Read the key from the environment; never print, log or commit it. - Keys: every key (`fk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`) draws from your account's one credit balance: your plan's credits, then overage on paid plans. Get one: a free account at https://dashboard.finks.ai/signin comes with a key; https://dashboard.finks.ai/keys makes more. - MCP: https://mcp.data.finks.ai/mcp (streamable HTTP), 11 read-only tools: sign in (OAuth) where the client supports it, else the same Bearer header. - Contract: the OpenAPI 3 spec at https://finks.ai/docs/openapi.json lists every route and field. - Errors: `{"error": {"code", "message", "request_id", "details"}}`. Branch on `code`; only `429 rate_limit.exceeded` sends `Retry-After`. - Paging: Search, while `has_more` is true, resend the same body with `cursor` set to `next_cursor`. Screener, while `next_cursor` is set, resend the query with `query.cursor` set to it. - Cite: show each result's source and date with any answer built on it. ## More - [llms.txt](https://finks.ai/llms.txt): every docs page as Markdown. - [OpenAPI spec](https://finks.ai/docs/openapi.json): every route and field. - [Data Library](https://dashboard.finks.ai/data): the datasets, their sources and how often they update.