AI Spec Discovery: Wrap an API That Has No OpenAPI Spec
Plenty of useful APIs never published an OpenAPI spec. AI Spec Discovery reconstructs one from their docs so you can still wrap them as MCP tools — here's how it works and where to be careful.
The clean version of wrapping an API assumes a spec exists. You paste an OpenAPI URL, the endpoints turn into tools, and you're done. But a lot of genuinely useful APIs never published one. There's a docs page with some curl examples, maybe a "getting started" guide, and that's it. No openapi.json, no Swagger UI, nothing machine-readable.
That gap is annoyingly common, and it's exactly what AI Spec Discovery is for. The short version: when there's no spec to import, an AI reads the API's documentation and reconstructs one. This post explains how that works, what it's good at, and — importantly — where you should keep a hand on the wheel.
The problem it solves
Automatic tool discovery needs structure. To turn an endpoint into a tool, the platform needs to know the path, the method, the parameters, and ideally a description — the stuff a spec spells out. When there's no spec, that structure only exists in prose written for humans: "Send a GET to /v2/search with a query parameter and an optional limit." A human can read that and know what to do. A spec importer can't parse an English paragraph.
Historically that left you two bad options: hand-write the spec yourself by transcribing the docs, or give up on the API. Both are why plenty of useful integrations never happen — the friction is just high enough to not be worth it.
How discovery works
AI Spec Discovery closes the gap by putting a language model on the reading-the-docs job. When you invoke it — the "Find it with AI" path, for an API where normal detection came up empty — here's roughly what happens:
The AI searches for the API's documentation, reads it, and produces an OpenAPI 3.1 definition describing what it found: the most useful endpoints (typically a handful, not an exhaustive dump), their parameters, and the provider-level authentication scheme the API uses. It deliberately focuses on the endpoints most likely to be worth calling rather than trying to reconstruct all two hundred routes, because a tight set of well-described tools beats a sprawling one a model can't navigate.
Two things it does not do, by design: it doesn't invent your secrets, and it doesn't claim certainty. The output describes auth type — "this API uses a bearer token" — not your actual token, which you still provide yourself. And every discovered endpoint comes back marked unverified, because it was inferred from documentation, and documentation lies. It's out of date, it has typos, it describes the endpoint that existed two versions ago. The AI is reading the same imperfect docs you would.
Why "unverified" is the honest part
I want to sit on that word for a second, because it's the difference between a useful feature and a footgun.
A reconstructed spec is a strong first draft, not ground truth. The AI might get a parameter name slightly wrong, miss that a field is required, or describe a response shape that changed. That's not a knock on the approach — it's the nature of inferring structure from prose. The right way to treat a discovered spec is as a hypothesis you're about to test, not a fact you're relying on.
Which is exactly how the system treats it. The endpoints stay flagged as unverified until something proves them out.
Verification that promotes itself
Here's the part I like. The proof doesn't come from a manual review step — it comes from actually using the thing.
When you wrap a discovered API and a tool call succeeds against the real API — the request goes out, your actual endpoint responds as expected — that's real evidence the inferred definition was correct. At that point the platform promotes the verified spec into its curated catalog. The next person who wants that same API gets the now-confirmed version instantly, no discovery needed, because reality already checked the AI's homework.
So the flow has a nice property: guesses get tested by use, correct guesses get promoted to known-good, and the catalog gets better every time someone successfully calls a newly discovered API. The unverified draft is a starting point that earns its way to verified by working.
When to reach for it
AI Spec Discovery is the right tool when:
- the API you want has no published spec in any importable format, and
- its documentation is decent enough for a model to read.
It's not the first thing to try. If the API publishes OpenAPI or Swagger, import that — it's authoritative and instant. If you have a Postman collection or even a HAR capture of real traffic, those carry more truth than reconstructed docs and the platform imports them directly. Discovery is the fallback for the genuinely spec-less API, which is precisely where it's most valuable because it's the case nothing else handles.
Practically, it's a metered feature — the kind of thing you spend a run on when it'll save you an hour of transcription. It's available on the paid tiers (Pro includes a monthly allotment of runs, Business more), which fits how it's meant to be used: not something you burn on APIs that already have specs, but a real out for the ones that don't.
The bigger point
The reason this matters isn't the feature itself — it's what it does to the set of APIs you can bring to your AI agents. Without it, "no OpenAPI spec" is a hard wall, and a surprising number of useful services are on the wrong side of it. With it, a well-documented API is wrappable whether or not anyone bothered to publish a machine-readable spec, and the wrapping gets more reliable over time as verified specs accumulate.
If you've got an API in mind that never shipped a spec — the one you keep meaning to integrate but haven't because the docs are all there is — this is the path. Wrap it, let a real tool call confirm the inferred endpoints, and see how it reads as MCP tools. The free tier is a fine place to start poking at it, and discovery is there on the paid plans when you hit an API that needs it.