> Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json.

# MCP server

Plug Finks into Claude, Cursor and any other agent.

## Endpoint

Claude, ChatGPT, Claude Code, Codex, Grok and Hermes sign in with OAuth. Cursor and VS Code use a key for now. Create one on [API keys](https://dashboard.finks.ai/keys). A key is also the fallback for CI.

MCP endpoint:

```text
https://mcp.data.finks.ai/mcp
```

## Add it to your client

**Claude** (sign in, no key). No API key needed: sign in to Finks.

1. Open **Settings → Connectors** and choose **Add custom connector**.
2. Paste the server URL, then choose **Connect**.
3. Sign in using your Finks login.

```text
https://mcp.data.finks.ai/mcp
```

**Claude Code** (CLI) (sign in, no key). Run this, then type /mcp, pick finks-api and sign in.

Terminal:

```bash
claude mcp add --transport http --scope user finks-api https://mcp.data.finks.ai/mcp
```

**CI / API key.** On a server or in CI, with no browser to sign in, create a key on [API keys](https://dashboard.finks.ai/keys), set it as `FINKS_API_KEY`, then: Run once in your project. Writes .mcp.json, which reads FINKS_API_KEY from your environment.

Terminal:

```bash
claude mcp add --transport http --scope project finks-api \
  https://mcp.data.finks.ai/mcp \
  --header 'Authorization: Bearer ${FINKS_API_KEY}'
```

**ChatGPT** (sign in, no key). No API key needed: sign in to Finks.

1. Turn on **developer mode** in ChatGPT's connector settings.
2. Add a connector with the server URL and authentication **OAuth**.
3. Sign in using your Finks login.

```text
https://mcp.data.finks.ai/mcp
```

**Codex** (CLI) (sign in, no key). Run these. The second one opens Finks sign-in.

Terminal:

```bash
codex mcp add finks-api --url https://mcp.data.finks.ai/mcp
codex mcp login finks-api
```

**CI / API key.** On a server or in CI, with no browser to sign in, create a key on [API keys](https://dashboard.finks.ai/keys), set it as `FINKS_API_KEY`, then: Add to the file. Reads FINKS_API_KEY from your environment.

~/.codex/config.toml:

```toml
[mcp_servers.finks-api]
url = "https://mcp.data.finks.ai/mcp"
bearer_token_env_var = "FINKS_API_KEY"
```

**Grok** (sign in, no key). No API key needed: sign in to Finks.

1. Go to **grok.com/connectors** and choose **New Connector → Custom**.
2. Paste the server URL.
3. Sign in using your Finks login.

```text
https://mcp.data.finks.ai/mcp
```

**Cursor** (key). Needs an API key. Add to `~/.cursor/mcp.json`. Reads FINKS_API_KEY from your environment.

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=finks-api&config=eyJ1cmwiOiJodHRwczovL21jcC5kYXRhLmZpbmtzLmFpL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciAke2VudjpGSU5LU19BUElfS0VZfSJ9fQ%3D%3D)

~/.cursor/mcp.json:

```json
{
  "mcpServers": {
    "finks-api": {
      "url": "https://mcp.data.finks.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FINKS_API_KEY}"
      }
    }
  }
}
```

**VS Code** (key).

1. Create a key on **API keys**.
2. Add this to `.vscode/mcp.json`. VS Code asks for your key once.
3. Check the connection.

[Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22finks-api%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.data.finks.ai%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24%7Binput%3Afinks-api-key%7D%22%7D%2C%22inputs%22%3A%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22finks-api-key%22%2C%22description%22%3A%22Finks%20API%20key%22%2C%22password%22%3Atrue%7D%5D%7D)

.vscode/mcp.json:

```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** (key).

1. Create a key on **API keys** and set it as `FINKS_API_KEY`.
2. Run this once in your terminal.
3. Check the connection.

Terminal:

```bash
gemini mcp add --scope user --transport http \
  --header 'Authorization: Bearer ${FINKS_API_KEY}' \
  finks-api https://mcp.data.finks.ai/mcp
```

**Hermes** (sign in, no key). No API key needed: sign in to Finks.

1. Add this to `~/.hermes/config.yaml`.
2. Run `hermes mcp login finks-api` and sign in using your Finks login.
3. In Hermes, run `/reload-mcp`.

~/.hermes/config.yaml:

```yaml
mcp_servers:
  finks-api:
    url: https://mcp.data.finks.ai/mcp
    auth: oauth
```

## CLI

Claude Code, Codex and Gemini CLI. The commands are with each client above: Claude Code and Codex sign in, and Gemini CLI reads `FINKS_API_KEY`.

- [Claude Code](#setup-claude-code)
- [Codex](#setup-codex)
- [Gemini CLI](#setup-gemini-cli)

## Tools

Each tool calls one route with the same filters and limits as the API.

- `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.

## Errors

A refused call returns a tool error with the API's error code and `request_id`. [Errors](https://finks.ai/docs/errors.md) lists the codes.