Your API's Next Customer Is an Agent: MCP, Skills, llms.txt, and HTTP 402

Somebody asked their coding assistant to "pull the last thirty videos from these forty YouTube channels and tell me which thumbnails changed." No human will read your documentation before that request executes. An agent will read whatever machine-readable surface you happen to have published, form a plan, and either call you correctly, call you forty times in a loop when one batch call existed, or decide you are too much trouble and go scrape the HTML.

That is the whole problem, and it is not a marketing problem. It is an interface problem, and you have somewhere between one and four surfaces available to solve it.

This post is about what each of those surfaces is for — they are not interchangeable, and shipping the wrong one first is the common mistake — and about the money question underneath them, which is further along than most people realise.

---

The four surfaces, and the job each one does

They stack. Each assumes the one before it.

Surface	Answers	Consumed by
openapi.json	What calls exist and what shape are they?	Codegen, tooling, an agent that can fetch and parse
llms.txt	What do I need to know before I plan?	Anything with a context window
MCP server	How do I actually call it, right now?	MCP clients — Claude, Cursor, Codex, and the rest
Agent skill	Which call should I make, and how do I not waste money?	Agent runtimes that support skills

An OpenAPI spec is necessary and nowhere near sufficient. ScrapeCreators' is 724 KB — a meaningful fraction of a context window spent on a document that is mostly parameter schemas for endpoints the agent will not call. A spec tells a model everything and emphasises nothing.

The other three exist because emphasis is the actual problem.

---

llms.txt: the file people fill with the wrong thing

The convention is simple — a Markdown file at /llms.txt describing your service for a model, with llms-full.txt as the expanded version. The mistake is almost universal: people generate it from their docs site and ship a table of contents.

A table of contents is what an agent can already derive from your spec. What it cannot derive is the decision rules — the things that change the plan it forms before it makes a single call.

Ours leads with billing, not endpoints:

## Billing rules an agent should know
- 1 credit = 1 request unless the endpoint says otherwise (see x-credit-cost in openapi.json).
- Failed requests are NEVER charged.
- Empty results are NEVER charged.
- Cache hits cost 0 credits. Add `cache_max_age=7d` to opt in.
- An invalid API key returns 401, not 402. A 402 always means the key is
  valid but the balance is not.

## Long-running work
Do not poll synchronous endpoints in a loop. Use:
- POST /v1/jobs — async, no timeout ceiling
- POST /v1/jobs/batch — up to 500 targets in one call
- POST /v1/subscriptions — get a webhook when data changes; you pay only on change

Every line there exists because it changes behaviour. "Failed requests are never charged" removes an entire category of defensive logic an agent would otherwise write — the try/catch that avoids calling a URL that might not exist. "Cache hits cost 0" is the single largest cost lever we have and an agent will never find it by reading parameter schemas. "Do not poll in a loop" is the failure we most expect, stated as an instruction rather than left to be inferred — an agent asked to "keep an eye on" forty channels will otherwise build a cron, and the bill for that pattern is brutal.

Then, and only then, the endpoint list — one line each, with cost and capability flags, generated from the same registry that generates the routes. Generated, not hand-written, because a hand-written llms.txt is stale within a month and a stale one is worse than none: it will confidently tell a model about an endpoint you removed.

Three rules that have held up:

1. Put the rules that change plans above the rules that describe calls. Cost, batching, caching, and error semantics before the catalogue.
2. Generate it from the same source of truth as your router. If adding an endpoint does not update this file automatically, it will drift.
3. Say what not to do. Negative instructions are unusually effective here and almost nobody writes them.

---

MCP and skills are not the same thing, and the difference is the whole point

This is the distinction that took us longest to internalise, and the clearest statement of it belongs to a competitor. ScrapeCreators put it this way in their own docs:

"The MCP server gives your AI agent direct API access — it can call ScrapeCreators endpoints on your behalf. The skill teaches the agent best practices for using those APIs: which endpoint to pick, how to handle pagination, what the credit costs are, and platform-specific gotchas. Use them together."

That is exactly right, and it is worth being precise about why.

MCP solves capability. An MCP server turns your endpoints into tools an agent can invoke. The wire format is small — JSON-RPC 2.0 over HTTP, a handful of methods: initialize, tools/list, tools/call, ping. Ours is served at POST /mcp on the same origin as the API, so a client configures it with a URL and the API key it already has:

{ "mcpServers": { "social-data": { "url": "https://api.example.dev/mcp" } } }

No npx, no local process, no second thing to update. A remote MCP endpoint on the same origin as your API is the right default in 2026 — the stdio variant exists for tools that cannot do HTTP auth, not as the primary path.

Two implementation notes that turned out to matter more than expected. First, every tool routes through the same execution pipeline as HTTP traffic — the same validation, cache, charge, refund, and logging path. If MCP gets its own code path, your billing guarantees drift between surfaces and you find out from a customer. Second, tool descriptions are where the cost model goes. Ours are generated per endpoint and append the facts an agent needs to plan: what it costs, whether a cached copy is acceptable, whether it needs infrastructure that may not be configured, and that failures are free. A tool description is not documentation. It is the only thing the model reads before deciding to call.

A skill solves selection. With fifteen endpoints, picking the right one is nearly free. With 179 across 29 platforms, endpoint selection is the hard part of using the API, and no amount of tool-schema polish fixes it — the agent is choosing between forty plausible options with a paragraph each. A skill is prose written for that decision: worked examples, the routing rules, the traps. Ours tells an agent that transcripts are immutable so cache_max_age=30d is always correct, that publishedAt on list endpoints is relative because that is what the platform renders, and that fifty creators means fifty subscriptions rather than a cron loop.

Note where that leaves the two of us. ScrapeCreators' skill is doing far more work than ours, because their selection problem is an order of magnitude harder and they solved it. They also ship it as an open-source repo installable across Claude Code, Cursor, Codex, Copilot, Gemini CLI, Windsurf and VS Code, and it produced the strongest testimonial they have — from a marketer, not a developer. That last detail is the strategically interesting one: a skill turns a developer API into something a non-developer can use, which is a market expansion, not a docs improvement.

Why you need both. MCP without a skill gives an agent forty hammers and no opinion about nails. A skill without MCP gives it excellent advice about calls it cannot make. The failure modes are different and both are real.

---

HTTP 402 stops being a joke status code

402 Payment Required has been reserved-for-future-use since 1997. The future arrived in a way that is easy to miss because it looks like an error.

Credit where it is due: ScrapeCreators shipped autonomous machine payments before almost anyone. A three-person bootstrapped team put a working 402 → pay → retry loop into production, with two payment rails. The flow:

1. The agent calls POST /mpp/buy-credits?pack=freelance.
2. The server replies 402 with a WWW-Authenticate: Payment header listing the rails it accepts.
3. The agent's payment client settles and retries with a payment credential in the Authorization header.
4. The server verifies, grants credits to the team behind the API key exactly once, and returns the new balance.

The rails are USDC on the Tempo network for the on-chain path and a Stripe Shared Payment Token for the card path, so a caller with no wallet is still served. Their reference client handles the whole loop.

One design detail in there is worth stealing regardless of whether you ever implement this: credits are derived from the verified payment amount, never from the request. The client does not say how much it bought. The server reads what was actually settled and grants accordingly. That is the difference between a payment endpoint and a vulnerability, and it is the kind of thing that gets skipped in a v1.

Read the significance correctly. Revenue from this today is almost certainly near zero. What it changes is a failure mode: when an agent runs out of credits halfway through a two-hour task, it buys more and keeps going. No human, no interruption, no abandoned job — and no churn event that started as "the agent stopped and nobody noticed until Monday."

We have not built this. Our own spec puts payment integration explicitly out of scope, and we return 402 in the boring way: as an error, meaning your key is valid and your balance is not. That is a correct use of the status code and a much less interesting one. The distinction is whether 402 ends a transaction or begins one.

---

What this does to pricing and packaging

Once the caller is a program, three things about your pricing change character.

Price becomes an input to planning, so it has to be machine-readable. Not a pricing page — a field. Every endpoint we expose publishes x-credit-cost in the OpenAPI spec, so "how much will this cost" is a computation rather than a support question. The state of the art elsewhere is thin: ScrapeCreators documents per-endpoint cost for 5 of 179 operations, and everyone else is worse. An agent that cannot compute the cost of a plan will either not check, or refuse to act.

Error semantics become billing semantics. An agent handed an ambiguous 402 — valid key, or empty balance? — will retry, top up, or halt, and two of those three are wrong. Separating authentication (401), authorisation, and billing (402) into three distinct outcomes stops mattering as a matter of taste and starts mattering because a program branches on it.

Guarantees remove code. "Never charged for failures" and "never charged for empty results" are not generosity, they are a smaller prompt. Every conditional an agent would write to avoid wasting credits is a conditional it now does not write, and each one it does not write is a place it cannot get the logic wrong.

The uncomfortable corollary: an agent will find the cheapest correct path through your pricing, every time, without sentiment. If your margin depends on customers not noticing the cache parameter, that margin is on a timer.

---

A checklist for making an existing API agent-legible

Roughly in order of value per hour spent.

1. Publish openapi.json at a stable URL, with per-operation cost. If cost varies, it is a field, not a footnote.
2. Write llms.txt by hand once, then generate it. Decision rules first, catalogue second, explicit "do not do this" third. Regenerate from the same registry that defines your routes.
3. Ship a remote MCP server on your existing origin, authenticated with your existing key. Route every tool through the same pipeline as your HTTP surface — no parallel code path for billing.
4. Put the cost model in the tool descriptions. That text is the only briefing the model gets.
5. Write the skill last, and write it about selection. If choosing between your endpoints is obvious, you may not need one yet. If it is not, no schema improvement will substitute.
6. Fix your error taxonomy before any of the above. An agent branches on status codes. Ambiguity there costs more than a missing surface.

Two things we have not done and are not going to pretend otherwise: there is no CLI and there are no official SDKs. Both are on the list; neither exists. A CLI in particular has a distribution property that is easy to underrate — ScrapeCreators ship a scrapecreators agent add cursor command that writes MCP configuration directly into someone else's AI tool, which is a genuinely clever way to be installed.

And one live tension we are unsure about: our tools/list requires authentication, so an agent cannot enumerate the catalogue before it has a key. That is defensible — the tool list is a product surface — and it also means discovery is gated behind a credential at precisely the moment an agent is deciding whether you are worth using. We are not confident that trade is right, and if we change our minds it will be because of that sentence.

---

For the reader who found this while deciding what to build first: the ordering above is the answer, and the surface you are most likely to overbuild is the spec while underbuilding the two paragraphs of prose that tell a model which call to make. Ours is a fifteen-endpoint API across four platforms, so our selection problem is easy and our skill is short. If yours has 179 endpoints, that ratio inverts, and the prose is the product.

If you want to see the shape rather than read about it, the reference table of what each social platform actually exposes without an API key is maintained here with test dates — that page exists in the form it does specifically because a model needs to be able to lift a correct answer out of it.

---

Sources. The ScrapeCreators distribution surfaces, the MPP flow, and the skill/MCP framing quoted above are recorded in research/06-distribution-and-ai-channels.md, gathered 2026-08-20 from their public docs and homepage. Their pack pricing and endpoint counts are in research/03 and research/07, same date. Vendor docs change — archive anything you plan to rely on.