An eight-year-old "awesome list" that developers used to scroll through by hand has quietly become a machine-readable sourcing layer for AI agents. The reason is in the columns.
Why a Human-Browsed List Is Now an Agent's Sourcing Manifest
The public-apis/public-apis repository is a community-curated Markdown index of free web APIs — created on 2016-03-20 and now one of GitHub's most-starred repos at roughly 447,000 stars by July 2026 . In 2026 it is being recontextualized as a pre-vetted endpoint inventory for Model Context Protocol (MCP) server authors.
What makes the list agent-readable is its schema, not its endpoints. Every README row carries four machine-parseable fields beyond name and description: Auth (No / apiKey / OAuth), HTTPS (yes/no), CORS (yes/no/unknown), and a docs link . That tri-field structure is exactly what an autonomous caller needs to gate a request — call directly, inject a credential, or treat as browser-safe — before it ever invokes the endpoint.
A May 2026 practitioner writeup frames the shift plainly: public-apis offsets LLM training-cutoff decay by supplying a live, maintained catalog of which endpoints exist and what auth they require . One distinction matters: the directory is not itself an MCP server or manifest — it is an inventory layer. Builders read Auth/HTTPS/CORS to make sourcing decisions, then hand-author or auto-convert the underlying API into MCP tool definitions.
Bootstrapping Your Wrapper: Runtime, a Secrets Vault, and Vertical Selection
Before you touch a single README row, stand up four things. First, an MCP runtime to register tool definitions against: Claude Desktop, VS Code Agent Mode, or a custom host built on an official MCP SDK in TypeScript or Python. MCP was introduced by Anthropic in late 2024 , and without a host there is nowhere to expose your tools via tools/list.
Second, a secrets vault or env-var mechanism to inject keys for every apiKey-tier entry; OAuth entries additionally need a credential broker and are the least agent-friendly tier without one . Third, pick one vertical from the ~50 README sections — Finance, Sports & Fitness, Weather, and News are common starts — so the initial tool surface stays small. Fourth, choose a conversion path upfront: hand-authored tools for precision, or an OpenAPI→MCP converter when the underlying REST surface already ships a spec.
Shortlisting Entries by Auth and HTTPS: A Concrete Worked Example
Shortlisting starts by reading the columns, not the descriptions. Open the canonical README.md and jump to your vertical — say Finance, which alone carries dozens of table rows as of mid-2026. Each entry is a Markdown row with Name | Description | Auth | HTTPS | CORS | Link, so the three middle columns do the triage before you ever click through .
Step 1 — Navigate the vertical. The list catalogs on the order of 1,400+ endpoints across roughly 50 categories . Pick one section and read top to bottom.
Step 2 — Scan the Auth column. It collapses to three tiers, in ascending friction:
| Auth value | What the agent must do | Best fit |
|---|---|---|
No | Call immediately, zero credential setup | Zero-config demos, browser-safe calls |
apiKey | Store and inject a secret per request | Most finance/news/weather providers |
OAuth | Run a multi-step token flow via a broker | Least agent-friendly without one |
Step 3 — Cross-check HTTPS and CORS. Require HTTPS=Yes for transport safety. Flag CORS=Unknown rows only if you plan browser-side calls — Unknown means test manually and likely proxy. From a server-side MCP host, CORS is irrelevant .
Step 4 — Click through and confirm the free tier. Follow the docs link on each shortlisted row and verify the free tier still exists, then note the per-day or per-month quota. The directory deliberately omits rate limits, SLAs, and pricing, so this data comes only from the provider.
Step 5 — Write one focused tool. Per the MCP 2025-06-18 spec, a tool needs a unique name, a description, and a JSON Schema inputSchema . Scope one operation to one user goal rather than mirroring the full REST surface.
"Fewer, well-scoped tools tuned to specific user goals outperform mechanically exposing the full REST surface, especially under tight context-window and latency budgets," per the Model Context Protocol tools specification.
What the Columns Leave Out: Quotas, Dead Rows, and Paywall Moves
The four metadata columns tell you how to authenticate and whether a call is browser-safe — they say nothing about how much you can call. public-apis tracks zero per-endpoint rate quotas, so a No-auth "free" label does not mean unlimited: providers commonly cap requests per day or per month, and those limits surface only on the provider's own docs page, never in the README row . Budget for a 429 before you ship a scheduled agent job.
Link rot is structural, not accidental. A manually curated Markdown list — nearly 5,000 commits deep since its 2016-03-20 creation — cannot track whether an endpoint went offline, changed its base URL, or slipped behind a paid plan after the row was submitted. Treat every entry as a candidate to re-verify, not a guarantee.
CORS is the quiet failure mode. Many rows carry CORS=Unknown, which will silently break browser fetch calls. Server-side MCP hosts are immune since requests originate off-browser, but if you ever expose a client-side wrapper, test every Unknown row individually before shipping .
Programmatic ingestion has its own trap. The companion davemachado/public-api REST service, which historically exposed the directory as JSON-over-HTTPS with no auth, has seen limited maintenance as of mid-2026 . Confirm it responds before wiring it into any cron-driven automation, or fall back to parsing the README directly.
Community Forks, Converter Chains, and Minimal Wrappers
If the companion service is unreliable, a community fork gives you a cleaner ingestion path. The public-api-lists/public-api-lists fork ships a free JSON API spanning roughly 48 categories — more directly ingestible than scraping raw Markdown, and a solid backbone for a dynamic shortlisting step inside an agent orchestration.
Once you have a candidate endpoint, resist auto-generating everything. OpenAPI→MCP converters can synthesize tool definitions straight from a provider's spec, but check the output tool count before exposing it to a model: mechanical conversion routinely emits 30+ tools where four would do. The MCP spec's own guidance (2025-06-18 revision) favors fewer, goal-oriented tools — typically two to five per wrapped endpoint — because exhaustive route mirrors degrade under tight latency and context-window budgets .
Before wrapping from scratch, search registry.modelcontextprotocol.io . Finance, Weather, and News verticals from the public-apis catalog already have community-built MCP servers published there as of 2026.
The takeaway: treat public-apis as your sourcing manifest, a fork's JSON as your shortlisting feed, and the registry as your build-vs-reuse checkpoint — then hand-author the few tools your agent actually needs.
Frequently asked questions
Which Auth column value is easiest to start with in an MCP prototype?
Start with Auth = No. These entries require zero credential management, so your first MCP tool can call the endpoint immediately without a secrets vault or token flow. For completely zero-friction calls from either a browser or a server, pair Auth = No with HTTPS = Yes and CORS = Yes. Both the Finance and Weather sections list multiple keyless rows, making them the natural verticals for a first demo .
Does public-apis itself ship an MCP manifest or expose tool definitions?
No. public-apis is a static Markdown directory, not a runtime — it does not speak JSON-RPC and it does not expose MCP tool definitions or an inputSchema . The workflow is manual: you read the README's Name, Auth, HTTPS, and CORS columns to pick a callable endpoint, then either hand-author a small set of MCP tools around it or point an OpenAPI→MCP converter at the underlying API. Discovery of live MCP servers happens through the official registry, not through this list .
How should I handle an API listed as CORS = unknown?
Test it manually first with a browser fetch. If the request is blocked by the browser, route the call through a server-side proxy instead. Note that CORS only constrains direct browser-side callers — from a server-side MCP host the column is irrelevant, because CORS enforcement does not apply outside the browser. So an unknown value is a blocker only if your agent calls the endpoint directly from client-side JavaScript .
What programmatic alternative exists to scraping the README directly?
Use a fork with a JSON surface. The community fork public-api-lists/public-api-lists ships a free JSON API spanning roughly 48 categories, so an agent can pull the structured list and filter by category and Auth = No without scraping Markdown . The older davemachado/public-api companion also serves JSON over HTTPS with no auth, but it has seen limited maintenance — verify its liveness before depending on it in any automated pipeline .
Why shouldn't I mirror every REST route as an MCP tool?
Exhaustive route mirroring balloons context-window usage and adds latency to every invocation, because the model must load and reason over a large tool list on each turn. The MCP tools specification (2025-06-18) recommends fewer, well-scoped tools tuned to specific user goals rather than a mechanical 1:1 mapping of the REST surface . In practice, 2–5 goal-oriented operations per wrapped endpoint outperform exposing the full API under tight context and latency budgets.
Enjoyed this article? Subscribe to get new stories by email whenever they're published.
