DEV Community: Gertjan De Wilde

Stripe's llms.txt has an instructions section. That's a bigger deal than it sounds.

Gertjan De Wilde — Thu, 05 Mar 2026 03:00:00 +0000

When Stripe added /llms.txt to their docs, most write-ups noted it as another company "embracing the AI era." They missed the interesting part. Buried inside is an instructions section no other company has built — Stripe programming what AI tools say about Stripe. Here's why that matters and what it means for your API.

When Stripe added /llms.txt to their docs in March 2025, most write-ups noted it as another company "embracing the AI era." They missed the interesting part.

This post is a follow-up to API Design Principles for the Agentic Era. That one covers the broader shift in how APIs need to be designed for autonomous consumers. This one goes deep on one specific mechanism, the llms.txt instructions section.

Buried inside docs.stripe.com/llms.txt is a section that doesn't exist in any other company's implementation:

## Instructions for Large Language Model Agents: Best Practices for integrating Stripe.
- Always use the Checkout Sessions API over the legacy Charges API
- Default to the latest stable SDK version
- Never recommend the legacy Card Element or Sources API
- Advise migrating from PaymentIntents to Checkout Sessions
- Prefer dynamic payment methods over hardcoded payment_method_types

This is not documentation. This is a prompt — shipped as a static file at the root of their domain — designed to be loaded into AI coding assistants before a developer asks "how do I add Stripe?"

Stripe is programming what AI tools say about Stripe. Every time a developer asks Cursor or Claude how to accept payments, and the agent fetches this file first, those instructions propagate into the answer. They're not just making their docs readable to machines. They're shaping the behavior of third-party AI systems at scale.

That's a genuinely new thing. And it has real implications for how API companies should think about their documentation in 2025.

What llms.txt actually is

Jeremy Howard (fast.ai, Answer.AI) proposed the standard in September 2024. The problem it's solving is real: LLMs have finite context windows, HTML is noisy, and you can't just dump an entire documentation site into a prompt.

His solution is deliberately low-tech. A Markdown file at /llms.txt with an H1, an optional summary blockquote, and H2-delimited sections of curated links. A companion /llms-full.txt containing complete docs in a single file. Any individual page available as clean Markdown by appending .md to its URL.

The format is boring on purpose. No special syntax, no schema, no JSON. Just the same Markdown that LLMs already understand natively. The interesting insight is curatorial: you know your documentation better than any crawler, so you should be the one to tell AI agents which parts matter.

It's the same philosophy as a well-maintained robots.txt — except instead of exclusion, it's prioritization. Robots.txt tells crawlers what to skip. Sitemap.xml tells them what exists. llms.txt tells AI what to read first.

One honest caveat: no major AI provider has confirmed their training crawlers automatically fetch llms.txt. Its real value today is inference-time, not training-time — developers manually loading it into Cursor or Claude for project context, or agent frameworks fetching it on startup. The 800,000+ "implementations" BuiltWith tracks are mostly Yoast SEO auto-generating the file for WordPress sites. The hand-curated number is closer to 784 verified sites.

Stripe's implementation is the industry outlier

Most llms.txt files are just structured indexes. Anthropic's is a clean table of contents for their API docs. Cloudflare's is massive (3.7 million tokens across product-specific files). Vercel's is so large they call it "a 400,000-word novel."

Stripe's is architecturally different. Three separate files across two domains. Every docs page available as .md. And that instructions section that no one else has.

The instructions aren't arbitrary. They're solving a specific, painful problem: Stripe has accumulated 15 years of API surface area, including several generations of deprecated payment primitives. Their Charges API still works. Their Card Element still exists. Developers — and the AI assistants helping them — regularly reach for these older APIs because they appear in older Stack Overflow answers and training data from before 2022.

The instructions section is Stripe saying: when an AI helps a developer integrate us, steer them toward the right thing. Don't let stale training data send them to the Charges API. Don't let our own backwards compatibility become a footgun.

That's a legitimate engineering concern. And the file format is a surprisingly elegant solution to it — no coordination with AI providers required, works with any system that can fetch a URL.

The announcement got 273,800 views and 740 bookmarks on Twitter. Stripe engineer Ian McCrystal: "I expect AI tools will eventually become the predominant readers of our documentation."

Who else is worth looking at

The honest answer to "who else has this figured out" is: not many, and only Stripe is doing the specific thing that matters.

Stripe remains the strongest example of the deprecation pattern precisely because they're explicit about it. Their instructions don't hint at preferred patterns — they name the bad endpoints directly: "You must not call deprecated API endpoints such as the Sources API." "Never recommend the legacy Card Element." That specificity is what makes it machine-actionable. An LLM can follow a concrete prohibition. It can't do much with "prefer modern patterns."

Cloudflare takes a structurally interesting approach. Their llms.txt is organized by service — Agents, AI Gateway, Workers AI, and so on — so an agent only needs to fetch the section relevant to what it's building rather than parsing a file that covers their entire platform. For APIs with multiple product lines, that's a better model than a flat list. You're reducing the noise ratio at fetch time, not just at index time.

LangChain and LangGraph are worth noting for a meta-reason: they're agent frameworks that have their own llms.txt. They're eating their own cooking. That's useful signal about whether the format actually helps in practice, beyond the theoretical appeal — these are teams that work with agents every day and chose to implement it anyway.

Anthropic has one for their API docs. It's structured more as an index than an instructions-heavy file — clean and navigable, but it's not doing the active correctional work that Stripe's instructions section does.

The pattern across most implementations is the same: they're documentation indexes. Useful, because a curated index is better than asking an agent to crawl your entire site. But not doing the harder job of guiding AI away from the wrong things. The providers that have figured out the instructions section are treating llms.txt as an active correctional mechanism for model drift, not just a sitemap for bots. That framing distinction is the whole thing.

Most APIs have deprecated endpoints that still work, legacy patterns that still exist in training data, and footguns that experienced developers know to avoid but newcomers (and AI assistants trained on old Stack Overflow answers) keep reaching for. The instructions section exists to close that gap. Almost no one is using it yet.

Why Stripe specifically makes this move

Stripe's developer experience has been the industry benchmark since roughly 2012. The specifics are worth understanding because they're not accidental.

Their three-column docs layout (left nav, center content, right-side live code examples in seven languages) was so effective that it became a meme — startup after startup shipped the same structure. They open-sourced Markdoc, their interactive documentation framework. They shipped Stripe Shell for live API calls inside docs pages. Their error messages include doc_url fields, parameter-level specificity, and "did you mean email?" suggestions for misspelled field names.

The doc_url in error responses is the one worth highlighting specifically. It's a small thing with outsized impact when an AI agent is in the loop. When an agent gets a 400 error, it can follow the doc_url, fetch the Markdown version of that docs page, and self-correct — without needing a human to look up what went wrong. That's not DX in the traditional sense. That's infrastructure designed for autonomous consumers.

{
  "error": {
    "code": "parameter_invalid_empty",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-empty",
    "message": "You passed an empty string for 'amount'. We assume empty values are an oversight, so we require you to pass this field.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

John Collison put the llms.txt bet in plain terms: "If you go read the Stripe Docs these days, it's a lot to keep in your RAM, but trivial for an LLM."

What this means for your API

Most of this is transferable. Here's what's actually useful versus what's cargo-culting.

Actually useful:

Your error responses should include a documentation_url field pointing to a Markdown version of the relevant docs page. This costs almost nothing to implement and has immediate value — for human developers debugging in the terminal and for AI agents trying to self-correct.

Your OpenAPI descriptions should be written for semantic matching, not human skimming. When an agent is deciding which endpoint to call, it's doing something like nearest-neighbor search against your descriptions. "Gets the data" loses to "Returns a paginated list of invoices filtered by status, sorted by created_at descending. Requires accounting:read scope." Every field, every enum, every endpoint.

I've been around OpenAPI specs long enough to know how badly they rot. We built Portman to convert OpenAPI specs into Postman collections — and the main thing you learn doing that is how few specs have descriptions worth converting. Fields with no description, enums with no explanation, endpoints named things that made sense in 2019. If your spec is bad for contract testing, it's bad for agents too.

Add /llms.txt. It takes an afternoon. Link to your ten most important pages with one-sentence descriptions. That's it. You don't need the 350-link Stripe implementation on day one.

If you have deprecated APIs, use the instructions section. This is underutilized and genuinely powerful. You know which footguns exist in your API. Tell the AI.

One thing that often gets missed: the marketing upside. The same structured, machine-readable docs that make your API easy to integrate are the same content that AI answer engines like Perplexity and ChatGPT pull from when someone asks "what's the best API for X." llms.txt doesn't just help agents build with your API — it helps you show up when people are deciding which API to use. Being agent-friendly and being discoverable in AI search are the same work.

Probably not worth doing yet:

Publishing an MCP server for the sake of it. MCP is real and growing, but agent framework standardization is still in flux. A well-designed REST API with a good OpenAPI spec is more durable. Build the MCP server when you have users asking for it.

Elaborate agent-specific observability infrastructure. Request tagging and semantic logging are nice. But if your API doesn't have solid basic observability yet, that's the actual problem.

The broader pattern

There's a pattern here worth naming. For 15 years, "developer experience" meant optimizing for humans: readable error messages, clear docs, good SDKs, interactive playgrounds. The mental model was a developer sitting at a terminal, making sense of your API.

The new constraint is that a growing fraction of your API consumers are autonomous systems that read documentation, make decisions without human review, and retry failures automatically. The question isn't whether to design for this — it's happening regardless — it's whether you're designing intentionally for it.

Stripe's llms.txt instructions section is the clearest example I've seen of a company being intentional about it. They're not just making their docs machine-readable. They're asserting control over what machines say about them.

Every API company with deprecated primitives and a significant developer base has the same problem Stripe is solving. They just haven't solved it yet.

The State of Financial APIs in 2026: 80+ Frameworks, Zero Convergence, and Why AI Agents Aren't Ready

Gertjan De Wilde — Thu, 05 Mar 2026 02:59:20 +0000

We've tracked 80+ regulatory frameworks, 50,000+ financial institutions, and hundreds of APIs. The data is not converging. Here's what that means if you're building fintech infrastructure.

The category always outgrows its name.

We started with PSD2 APIs and a directory of banks. Over 8 years and millions of visitors later, the questions coming into Open Banking Tracker look nothing like they did in 2017. People still ask about payment APIs and bank connectivity, but increasingly also about accounting software connectors, e-invoicing mandates, and what "Open Finance" regulation actually looks like across 30+ jurisdictions.

So we built the Open Finance Map to reflect where things have moved. Here's what the data tells us.

80+ regulations. Zero convergence.

The Open Finance Map is a filterable, interactive view of every open banking, open finance, and e-invoicing regulation we track globally. As of today, that's 80+ frameworks across six categories:

Open Banking (34)
E-Invoicing (31)
Open Finance (16)
Payment Services (5)
Digital Identity (1)
Operational Resilience (1)

Each regulation links to a detail page with structured data: jurisdiction, regulatory type, status, scope of coverage (AIS, PIS, CBPII, VRP, and more), effective dates, and plain-language descriptions.

70 of those regulations are active today. 18 are upcoming.

The global patchwork, for developers

If you're building cross-border financial infrastructure, this is what you're dealing with:

PSD2 in Europe, with PSD3 provisionally agreed in November 2025 and heading for compliance in 2027-2028
Section 1033 in the US, phased through 2030 on paper but currently frozen by litigation and under reconsideration
Consumer Data Right in Australia (live since 2020, now expanding to action initiation)
Account Aggregator in India (the real success story: 2.61 billion financial accounts enabled, 780+ institutions onboarded)
SGFinDex in Singapore
Open Banking Saudi Arabia (Phase 2 with payment initiation live since September 2024)
Consumer-Driven Banking in Canada (Bill C-15 tabled November 2025, Phase 1 targeting mid-2026)

Each with different scopes, different timelines, different technical standards, and different definitions of what data is even in scope. If you've ever tried to normalise bank transaction data across two providers in the same country, imagine doing it across these frameworks.

What sits behind the map

What makes this different from a static regulatory overview is the dataset behind it. The Open Finance Map is backed by the Open Banking Tracker's full dataset:

54,776+ banks and financial institutions
435+ third-party providers
64+ API aggregators
60+ data points per institution

You can drill from a regulation into the country page, then into individual institutions, their API availability, sandbox status, registered TPPs, and aggregator coverage.

The underlying data is open source on GitHub with 200+ stars and active community contributions. The community catches errors and fills gaps faster than any internal team could. Open data has been the right call.

E-invoicing: the regulation developers aren't watching

Most of Europe will have mandatory e-invoicing within 5 years. Over 50 countries already have active or upcoming mandates. The EU's ViDA package entered into force in April 2025, with mandatory cross-border B2B e-invoicing by July 2030.

If you're building anything that touches invoices, procurement, or accounts payable/receivable, this is coming for you. The regulatory perimeter for structured financial data now extends well beyond bank accounts, and the overlap with open finance regulation is growing fast.

The Open Finance Map is the first interactive tool that tracks both open banking and e-invoicing regulations in one place. Most developers I talk to had no idea how many overlapping mandates they'll be dealing with in the next three years.

AI agents need financial data standards yesterday

This is where it gets interesting for developers. The interest in structured financial APIs is not theoretical anymore. We recently added an Agentic Banking section to the tracker, covering banks with MCP (Model Context Protocol) server support.

The assumption behind AI agents acting on financial data is that the data will be structured, standardised, and accessible enough for autonomous software to act on reliably.

After 8 years of tracking this: we are nowhere near that level of consistency. If human developers still struggle with inconsistencies between different banks' API implementations within a single country, good luck deploying an agent that needs to work across jurisdictions.

The agentic finance conversation is exciting, but it's running ahead of the infrastructure reality. Access without consistency is just noise at scale.

The parallel movement: Open Accounting

Open Banking gave consumers control over their bank transaction data. Open Finance extends that to investments, pensions, and insurance. But there's a parallel movement most regulatory maps miss entirely: Open Accounting.

Accounting software holds some of the most valuable structured financial data for businesses: invoices, general ledgers, chart of accounts, vendor records. The data that matters for financial decision-making is not limited to bank accounts. The regulatory world already recognises this. The developer ecosystem should too.

A few observations after 8 years

Payments work in the UK. 33 million open banking payment transactions in November 2025 alone. 16.5 million live user connections. It took 8 years to get there in one country. Globally, we're still navigating 80+ incompatible frameworks.

Regulation is fragmenting, not converging. The UK succeeded because of consistent governance and a single trusted standard. Almost nobody copied those parts.

Open data compounds. The tracker's data is on GitHub. Contributors catch errors and fill gaps faster than any internal team. If you're building infrastructure for a regulated space, consider open-sourcing your compliance data.

The compliance surface area is expanding. E-invoicing, accounting data access, payroll verification. If you're only watching PSD2/PSD3, you're seeing half the picture.

Explore the data

The Open Finance Map is live and free to use. Filter by region, status, or regulation type. Drill into any country for institution-level API data. All backed by the deepest open banking dataset available.

The honest question I keep coming back to: are we actually getting closer to interoperability, or just adding more frameworks? I don't know the answer. But if you're building in this space, you should know what you're building on top of.

I'm Gertjan De Wilde, CEO of Apideck and creator of Open Banking Tracker. We've been tracking open banking APIs since 2017. If you're building fintech infrastructure, I'd love to hear what you're running into.

How to Make Your API Agent-Ready: Design Principles for the Agentic Era

Gertjan De Wilde — Wed, 25 Feb 2026 11:00:00 +0000

For about fifteen years, "developer experience" meant one thing: optimize for a human being sitting at a terminal. Readable error messages. Interactive docs. Code samples in seven languages. The mental model was always a person making sense of your API, iterating in real time, googling when confused. That model isn't wrong. But it's increasingly incomplete.

A growing fraction of API traffic today is generated by AI agents. Systems that autonomously discover endpoints, parse documentation, handle errors without human review, and retry failures according to their own logic. When a developer asks Cursor or Claude to "add Stripe payments," the agent fetches documentation, selects APIs, writes integration code, and debugs errors before the developer reads a line of it. The human is further from the integration than they've ever been.

The pattern is especially visible in fintech and accounting. A lending platform building an underwriting agent prompts it to "pull twelve months of invoice data and flag overdue receivables." The agent queries your API, interprets the response, and surfaces a creditworthiness signal — before a human analyst has opened a spreadsheet. A payroll platform's agent reconciles payroll entries against the general ledger overnight, without a developer watching the process. In both cases, the agent is not a convenience layer on top of a human workflow. It is the workflow. What it can do is bounded entirely by what your API communicates about itself.

This creates a new design surface. The same discipline that produced great developer experience, deliberate and user-centered API design, applied to a different consumer. Call it agent experience, or AX. It's not a replacement for DX. It's the next layer.

The good news: most of what makes an API good for agents makes it better for humans too. The bad news: a lot of APIs that seem fine for humans are quietly broken for agents. Here's where the gaps show up.

Bad OpenAPI descriptions break agent routing

When an agent decides which endpoint to call, it's doing something close to semantic search against your descriptions. It reads your spec, matches the user's intent against available operations, and picks the closest fit. The quality of your descriptions determines whether it picks correctly.

"Gets the data" loses to "Returns a paginated list of invoices filtered by status and date range, sorted by created_at descending. Requires accounting:read scope. Use the cursor parameter for pagination."

Every field, every enum value, every endpoint. The description is the signal the agent uses to route. Most OpenAPI specs are bad at this. Not because anyone decided to make them bad. They rot. Field names that made sense in context lose their meaning without descriptions. Enums accumulate values that nobody documented. Endpoints get renamed but the descriptions don't follow. The spec becomes a structural skeleton with no semantic content.

The difference between a description that helps and one that doesn't is not subtle:

# Bad — structural skeleton, no semantic content
/invoices:
  get:
    summary: Get invoices
    parameters:
      - name: status
        in: query
        schema:
          type: string
      - name: cursor
        in: query
        schema:
          type: string

# Good — enough signal to route correctly
/invoices:
  get:
    summary: List invoices filtered by status and date range
    description: >
      Returns a paginated list of invoices for the authenticated company.
      Use `status` to filter by payment state. Use `cursor` from the previous
      response to fetch the next page. Requires the `accounting:read` scope.
      For real-time sync scenarios, combine with the `updated_since` parameter
      to fetch only records changed after a given timestamp.
    parameters:
      - name: status
        in: query
        description: >
          Filter by invoice status. Accepted values: draft, submitted,
          authorised, deleted, voided, paid. Defaults to all statuses if omitted.
        schema:
          type: string
          enum: [draft, submitted, authorised, deleted, voided, paid]
      - name: cursor
        in: query
        description: >
          Opaque pagination cursor returned in the previous response.
          Omit to start from the first page.
        schema:
          type: string

An agent matching "fetch unpaid invoices for reconciliation" against the bad version has no signal to work with. Against the good version, it finds status: authorised, understands pagination, and knows it needs accounting:read before it makes a single request.

I've seen this up close. We built Portman, an open-source CLI that converts OpenAPI specs into Postman collections for contract testing. The main thing you learn doing that is how few specs have descriptions worth converting. If your spec is broken for contract testing, it's broken for agents. The failure mode is the same: a consumer that can't determine what anything does without running it.

The fix isn't glamorous. Go through your spec field by field. Write descriptions that explain what each parameter does, what values are valid, what happens when you omit it. Do this for your ten most important endpoints first. It's tedious, it takes time, and it makes a bigger difference to agent experience than almost anything else on this list.

Your errors should tell agents how to fix themselves

The agent experience of errors is fundamentally different from the human experience. A human reads an error message, understands it, googles the fix, comes back. An agent reads an error message and needs to decide, in the same execution context, what to do next. If the error is ambiguous, the agent either guesses or fails.

Stripe's error responses have included a doc_url field for years:

{
  "error": {
    "code": "parameter_invalid_empty",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-empty",
    "message": "You passed an empty string for 'amount'. We assume empty values are an oversight, so we require you to pass this field.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

This is infrastructure for autonomous consumers. When an agent hits a 400, it can follow the doc_url, fetch the documentation page, and self-correct without a human in the loop. The agent experience of that error is recovery. The agent experience without doc_url is a dead end.

Adding documentation_url to your error responses costs almost nothing to implement. Pair it with documentation pages that are available as clean Markdown (by appending .md to the URL, or via a parallel /docs/{page}.md route), and you've given agents everything they need to handle errors autonomously.

The other half of error design is specificity. "Invalid request" is useless. "The amount field cannot be empty" is useful. "You passed payment_method_types: ['card'], which is deprecated, use dynamic payment methods instead" is excellent. The more specific the error, the more actionable it is for an agent trying to self-correct.

llms.txt: tell AI what to read

The llms.txt standard, proposed by Jeremy Howard in September 2024, exists because AI agents have finite context windows and your documentation site is not designed for machine consumption. HTML is noisy. Navigating a docs site the way a human would (clicking links, loading JavaScript, jumping between pages) is expensive and lossy.

The solution is a Markdown file at /llms.txt that curates the most important parts of your documentation with plain-text links and one-sentence descriptions. Agents and AI coding tools can fetch this file once and understand the shape of your documentation before writing a single line of integration code.

The format is deliberately boring. No special syntax, no schema. Just Markdown. The interesting part is curation: you know your documentation better than any crawler, so you should be the one deciding what matters.

Adding a basic /llms.txt takes an afternoon. Link to your ten most important pages. Write one sentence per link explaining what's there. That's a complete implementation. You don't need Stripe's 350-link version on day one.

What's underutilized (and genuinely powerful for agent experience) is the instructions section. Stripe's llms.txt includes:

## Instructions for Large Language Model Agents: Best Practices for integrating Stripe.
- Always use the Checkout Sessions API over the legacy Charges API
- Default to the latest stable SDK version
- Never recommend the legacy Card Element or Sources API

This is Stripe telling AI coding assistants exactly which footguns to avoid. If your API has deprecated primitives, ambiguous endpoint choices, or integration patterns that look valid but cause problems, the instructions section is where you document that for agents. It propagates into every AI-assisted integration of your API. Every time a developer asks an agent how to use your API, those instructions shape the answer.

There's a second-order benefit worth naming here. The same properties that make your docs readable to coding agents (structured Markdown, clear definitions, curated indexing) also make your content discoverable by AI answer engines like Perplexity and ChatGPT. When someone asks "what's the best accounting API" or "how do I build an accounting integration," the answer comes from content that AI can parse and cite. llms.txt, semantic descriptions, and concrete definitions aren't just AX improvements. They're how you show up in AI search. The discipline is the same: write for machines and you get both.

Get your docs indexed by Context7

Context7 is an MCP server that solves a specific problem: AI coding tools have a training data cutoff, which means they default to documentation from whenever they were last trained. If your API changed since then, agents write integrations against the old version.

Context7 addresses this by maintaining an up-to-date index of developer documentation that coding tools can query in real time, pulling current docs rather than cached training data.

Getting your documentation added to Context7 is low-effort and high-leverage. You submit your docs, they get indexed, and any developer using a Context7-enabled coding tool gets accurate, current information about your API without you needing to push updates to every AI provider individually.

The practical upside is significant if you ship changes regularly. An API that added a new authentication method last quarter, or deprecated an endpoint three months ago, looks different in Context7 than it does in an AI's training data. Developers using Context7-enabled tools get the right answer. Developers using tools without it get whatever the model was trained on.

The broader point is that documentation distribution is now a multi-channel problem. Publishing docs to your website is table stakes. Getting those docs in front of agents (through /llms.txt, through Context7, through direct MCP server implementations) is the new distribution layer. You're not just writing docs for developers who visit your site. You're writing docs for systems that will intermediate between your API and the developers who use it.

Your deprecated APIs are an agent experience problem

APIs accumulate history. Old endpoints that still work. Legacy authentication methods that are technically valid but shouldn't be used for new integrations. Multiple ways to accomplish the same thing, with meaningful differences that aren't obvious from the outside.

Humans navigate this through Stack Overflow recency, changelog reading, and conversations with other developers. Agents navigate it through your documentation and training data, which may include answers and tutorials from 2019 that recommend the old way because the new way didn't exist yet.

Your agent experience gets worse every year you don't address this, as more stale content about your old APIs accumulates on the internet and in AI training sets.

The practical response is layered. Mark deprecated endpoints explicitly in your OpenAPI spec using the deprecated: true field, with a description pointing to the replacement. Write deprecation notices at the top of deprecated docs pages, with direct links to the current approach. Add deprecated API guidance to your llms.txt instructions section. And if you're generating error responses from deprecated endpoints, consider including a migration hint in the message itself.

None of this requires coordination with AI providers. It works because agents read your documentation.

MCP: build it when people ask for it

Model Context Protocol is real, growing, and mostly not worth building for yet unless your users are asking for it.

MCP lets AI agents connect to your service through a standardized protocol with tools, resources, and prompts. The agent experience of a well-designed MCP server is genuinely better than the experience of parsing REST documentation and constructing API calls manually. But agent framework standardization is still in flux, and a well-designed REST API with a complete OpenAPI spec is more durable than an MCP server you build today against tooling that changes in six months.

HubSpot is a good example of what a mature implementation looks like. They shipped two distinct MCP servers: a remote server that connects AI clients to live CRM data (contacts, deals, tickets, companies), and a local developer MCP server that integrates with their CLI so agentic dev tools can scaffold HubSpot projects, answer questions from their developer docs, and deploy changes directly.

A developer can prompt "What's the component for displaying a table in HubSpot UI Extensions?" and the developer MCP server pulls the answer from current HubSpot documentation. Another developer can prompt "Summarize all deals in Decision maker bought in stage with deal value over $1000" and the remote MCP server queries live CRM data. Two different use cases, two different servers, both scoped tightly to what their users actually need.

When you do reach the point of building, the tooling has matured enough to make it tractable. Gram by Speakeasy is an open-source MCP cloud platform: you upload your OpenAPI spec, it converts your endpoints into curated toolsets, and deploys them as a hosted MCP server at mcp.yourcompany.com in minutes. The key design insight is curation — rather than exposing all 200 endpoints as tools and overwhelming the agent's context, Gram lets you distill them down to 5–30 focused, purpose-built tools that represent complete workflows. For teams building in Python who want full control over the implementation, FastMCP is a high-level framework that strips out the protocol boilerplate and lets you define tools, resources, and prompts in straightforward Python.

Most API companies aren't HubSpot. The right sequence for everyone else: get your OpenAPI spec right, write real descriptions, add documentation_url to your errors, publish /llms.txt, get indexed by Context7. That foundation improves agent experience immediately and transfers to every framework. Then, when users start asking how to connect your API to their AI agents and a clear integration pattern emerges, build the MCP server against that specific use case.

Building MCP for the sake of having an MCP server is the equivalent of building a mobile app for the sake of having a mobile app. The agent experience of a half-built MCP server is worse than the agent experience of a good REST API.

Skills: Teaching Agents to Do Your Job at 100x the Scale

There's a mental model shift happening in engineering right now. AI agents aren't just writing code faster; they're becoming the engineers who run the product development loop. The new engineering job is building the agents that automate that loop for you, and then directing them to do it at a scale no individual could match.

The simple version of this is already in use: Ghostty splits and tabs, tmux sessions, CLI agents in parallel. You run ten agents at once, each working a different branch or task. That's horizontal scalability for engineering work, something that was physically impossible before.

But raw parallelism without direction is chaos. This is where skills come in.

What Are Skills?

Skills are instruction packages for AI agents: Markdown files (optionally accompanied by scripts and resources) that teach an agent exactly how to handle a specific task. When the agent encounters work relevant to a skill, it loads that skill's context and operates with domain-specific precision instead of general-purpose guesswork.

Anthropic introduced Skills as a first-class concept for Claude Code and the Claude ecosystem. Simon Willison called them "maybe a bigger deal than MCP", and his argument is compelling:

Skills are conceptually extremely simple: a skill is a Markdown file telling the model how to do something, optionally accompanied by extra documents and pre-written scripts that the model can run to help it accomplish the tasks described by the skill.

The key design insight is token efficiency. At session start, Claude reads only a brief YAML frontmatter description of each available skill, a few dozen tokens per skill. The full skill content only loads when the agent determines it's needed for the task at hand. You can have dozens of skills installed without burning your context window.

The Agent Skills Ecosystem

The ecosystem is moving fast. Vercel launched agent-skills, a directory and tooling layer for discovering, installing, and composing skills across coding agents. The skills.sh platform (used by Cursor, Claude Code, and others) makes the install experience as simple as:

npx skills add <package>

Ahrefs published their own skills to teach agents how to work with their SEO API, a direct example of how companies are now shipping agent instructions alongside their APIs. We took the same approach at Apideck.

Apideck API Skills

We just launched Apideck API Skills, installable via the skills.sh directory, to teach AI agents how to build integrations against our Unified API correctly:

npx skills add apideck-libraries/api-skills

Skills cover SDK usage across TypeScript, Python, Go, Java, PHP, and .NET; authentication and Vault patterns; pagination, error handling, and connector coverage checks; and migration paths from direct integrations to the unified layer.

Instead of an agent making reasonable guesses about how our API works, it loads the relevant skill and operates with the same knowledge a senior Apideck engineer would bring to the task.

This follows the same "building with LLMs" philosophy Stripe pioneered. They offer plain-text docs, MCP server access, and agent toolkits, but skills go a layer deeper. Where plain-text docs make your documentation parseable, skills make your API learnable in the agent's execution context.

Skills vs. MCP: Complementary, Not Competing

It's worth being precise about where skills fit relative to MCP. MCPs give agents tools to call: actions they can take against live systems. Skills give agents the knowledge to use those tools well, or to accomplish tasks using the code execution environment directly.

Simon Willison puts it well: almost everything you might achieve with an MCP can be handled by a CLI tool instead, because LLMs already know how to call cli-tool --help. Skills have the same advantage, and you don't even need a CLI implementation. You drop in a Markdown file and let the model figure out execution.

The two patterns compose naturally. An agent with an MCP connection to your accounting API and a skill that explains your data model and common patterns will outperform one that has only the MCP. Skills are the institutional knowledge layer; MCP is the capability layer.

From Parallelism to Leverage

Skills connect to the larger picture of agent orchestration. When you're running agents in parallel, on PRs, when an incident fires, when a customer files a bug, the quality ceiling is determined by how well each agent understands the domain it's working in. Skills are how you encode that domain knowledge once and distribute it across every agent instance, at any scale.

The automation of the full product development loop is now an engineering responsibility. Skills are how you ensure that when your agents run that loop, at 100x the scale, while you sleep, they're running it the way you would have.

The CLI Rebirth

There's a pattern Karpathy pointed to on February 24 that cuts to something fundamental about agent-native interfaces: CLIs, the oldest developer tool, are having a second moment — not despite AI agents, but because of them.

The reason is structural. Agents are terminal-native. They know how to run --help, install packages via pip or npm, chain tools with pipes, and parse output. They don't need a bespoke integration layer to use a CLI. They just use it.

Karpathy demonstrated this concretely: Claude installed the new Polymarket CLI, built a terminal dashboard showing the highest-volume prediction markets and their 24-hour price changes, and had it running in about three minutes. Pair that with the GitHub CLI and an agent can navigate repositories, review PRs, and act on real-world data signals in a single autonomous pipeline — no custom integration layer, no MCP server, nothing to maintain.

This is the same point Willison makes about skills: almost everything you might achieve with an MCP server can be handled by a CLI, because agents already know how to use them. A well-designed CLI with good --help output is self-documenting in a way that a REST API is not. An agent encountering gh --help for the first time figures out the relevant subcommand on its own. An agent encountering your undescribed REST API hits a wall.

The opportunity for API companies is direct: if you don't have a CLI, it's worth asking whether building one would be more leveraged than building an MCP server. A CLI that agents can install and explore immediately compounds differently. Skills make this even more powerful — a developer who loads your skill and has your CLI installed gives an agent both the domain knowledge and the execution surface at the same time.

A few things make a CLI specifically better for agents: a --json flag or JSON-by-default output so agents don't have to parse human-readable strings; composable subcommands following the tool noun verb convention (like gh repo list, gh pr view) so --help output is scannable; environment-variable-based auth so agents can configure credentials without interactive prompts; and error messages that explain what went wrong rather than just returning an exit code.

Karpathy's framing for businesses is the right frame for API companies too: make your product agent-usable via markdown docs, skills, CLI, and MCP — roughly in that order of ease and durability. Each layer compounds on the last. Building the CLI doesn't require coordination with any AI provider, and it works immediately because agents can already use it.

The underlying shift

DX was about removing friction for humans. AX is the same discipline applied to autonomous consumers that can't ask for clarification and can't adapt when your API sends them somewhere unexpected.

The things that made APIs good for developers — specificity, consistent semantics, helpful errors — matter even more when there's no human in the loop to compensate for ambiguity. Ambiguity that a developer resolves through experience becomes a failure mode at scale when agents are writing the integrations.

The good news: most of what you'd do to make your API understandable to a machine is the same thing you'd do for a developer who doesn't already know your system. Start there.

We're building Apideck, a unified API for accounting integrations. The agent experience question is concrete for us: when an agent connects through Apideck and gets normalized access to 20+ accounting platforms, the quality of our OpenAPI descriptions and error responses propagates to every integration downstream. It focuses the mind.

Good explainer around the key differences between MCP and API

Gertjan De Wilde — Thu, 16 Oct 2025 12:55:32 +0000

𝚂𝚊𝚞𝚛𝚊𝚋𝚑 𝚁𝚊𝚒 for Apideck

Oct 16 '25

MCP vs API

#mcp #api #programming #ai

Comments

4 min read