For AI agents

Data Access for AI Agents

Annalist data is available as JSON, CSV and Excel, through a read-only MCP server and with a description for language models, so that an agent can quote a figure with its document. Access requires no account or key.

MCP server

https://annalist.io/mcp

Streamable HTTP, JSON responses, no session. Read-only tools.

Guide for models

/llms.txt and /llms-full.txt

The coverage, the conventions and how to cite, in the llms.txt format.

API description

/api/v1/openapi.json

OpenAPI 3.1 description of the static JSON and CSV endpoints.

Company list

/api/v1/companies.json

Ids, names, tickers and the latest snapshot of each company.

Workbook

/company/{id}/{id}.xlsx

One Excel workbook per company, with its statements, ratios, findings and checks.

Install in One Click

Each button opens the client, which asks before it adds the server. The server needs no account, key or sign-in.

Add to Cursor Add to VS Code

Claude

On the web, in the desktop app or on a phone, open Connectors in the settings, choose Add custom connector and paste the server address above. No sign-in is needed.

ChatGPT

Turn on developer mode in the settings of apps and connectors, create a connector with the server address above and choose no authentication. Deep research and company knowledge use the tools search and fetch.

Other clients

Any client that supports remote MCP servers over HTTP takes the server address above. Directories and clients read the server card at /.well-known/mcp/server-card.json.

Connect an Agent

Any client that supports remote MCP servers over HTTP can use the server URL above.

Claude Code

claude mcp add --transport http annalist https://annalist.io/mcp

Project Configuration (.mcp.json)

{
  "mcpServers": {
    "annalist": { "type": "http", "url": "https://annalist.io/mcp" }
  }
}

Python Without an MCP Library

A request to the MCP server is one JSON-RPC message in a POST, so a tool call needs no session and no initialize request first.

Python Standard Library

import json, urllib.request

body = {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": {"name": "search_companies",
                   "arguments": {"query": "AAPL"}}}
req = urllib.request.Request(
    "https://annalist.io/mcp",
    data=json.dumps(body).encode(),
    headers={"Content-Type": "application/json",
             "Accept": "application/json, text/event-stream",
             "User-Agent": "my-agent/1.0"})
with urllib.request.urlopen(req) as r:
    print(json.load(r)["result"]["structuredContent"])

The User-Agent header in this example is required. The hosting service answers HTTP 403 (Cloudflare error 1010) to every request whose User-Agent starts with Python-urllib, the default of the Python standard library, or with libwww-perl, on the MCP server, the static API and llms.txt alike. The MCP Python SDK, requests, httpx, curl and browsers send other User-Agents and need no change.

Tools

All tools are read-only and return figures with units, methods and source ids.

search_companies

Companies by name, ticker, SEC CIK or id, with a country filter.

get_company_overview

One answer on a company: the latest revenue and net income with their change against a year earlier, the latest value of each measure, the current key findings, its peers and its data quality.

get_statement

Figures of one statement with units, methods and source ids, for a range of fiscal years, quarters or dates.

get_ratios

Ratio values with formula ids, units and the snapshot figures each value was computed from.

get_findings

The current key findings, each a sentence with its rule, state, figures and source ids, and the history of each finding on request.

screen_companies

Companies filtered and ranked by the latest value of a measure, by market, sector or industry; an amount is compared within one currency.

compare_companies

2 to 4 companies side by side on calendar quarters, as Compare places their fiscal periods, each value in the currency of its company.

get_events

Acquisitions, disposals, spin-offs, stock splits, restatements and the other corporate events, each with its date and source ids.

get_data_quality

The data quality of a company: the values that checks confirm, the values derived, the values withheld with their reasons and the figures restated with the document of each value.

get_snapshot_info

Coverage, conventions, the validation summary, statements, files and the citation format.

list_snapshots

Every snapshot published for a company with its time of publication, for an answer as at an earlier date.

get_sources

Source documents with URL, release or filing date and SHA-256.

run_buyout

The buyout model of Deal Lab on the published figures, at its starting values or with the assumptions given: returns, the debt schedule, the covenants and the checks of the model, each input with its source documents, and the address of the same deal on the site.

search, fetch

The documents of the companies that a question names, in the form that ChatGPT connectors and deep research use, each with the address of its page.

Prompts

Clients that show the prompts of a server, as slash commands or in a menu, offer 3 tasks with their steps and the citation format.

company_brief

A brief of one company from its overview and its key findings.

credit_review

The credit metrics, liquidity, earnings quality and scores of one company.

peer_comparison

2 to 4 companies on calendar quarters, with their margins, returns and debt against EBITDA.

Static API

Plain files behind a cache of 5 minutes, with cross-origin access allowed.

Latest Snapshot of a Company

curl https://annalist.io/api/v1/companies/apple/latest.json

One Statement

https://annalist.io/api/v1/companies/{company}/snapshots/{snapshot}/statements/pl_quarterly.json

Ratios of One Frequency

https://annalist.io/api/v1/companies/{company}/snapshots/{snapshot}/ratios/ttm.json

Every Company With Its Latest Measures

https://annalist.io/api/v1/overview.json

Calendar Quarters of a Snapshot

https://annalist.io/api/v1/companies/{company}/snapshots/{snapshot}/calendar.json

Citation

Each figure should be cited with its snapshot and its source document.

Annalist, {company name}, snapshot {company id}/{snapshot id} (as of {period}); {item label}, {period}; source {document id} ({document url})