Going Headless Isn't the Hard Part

For years, the SaaS playbook was simple: Build a beautiful, useful interface so you can win workflows. Then, have over-caffeinated recent college grads cold call customers like their life depended on it. It was simple, but it worked.

Then Salesforce declared itself headless, exposing every capability in its platform as an API, MCP tool, or CLI command so agents could operate the system without ever opening a browser. AI agents would recommend the software, then AI agents would operate the software, turning the entire model on its head (no pun intended).

To add fuel to the fire, one April morning, OpenAI rolled out Workspace Agents in ChatGPT — shared agents that handle complex tasks and long-running workflows, powered by Codex and replacing Custom GPTs. The agents that will run enterprise workflows in 2027 are being built right now, and they are not bothering to open that user interface you so carefully designed. To really drive the point home, in February, Sam Altman said that “Every company is now an API company, whether it wants to be or not.”

Agents are coming for everything, and they are coming now. Every SaaS founder I talk to understands this. They know the UI is losing its primacy. They know agents are going to be an important user of their product inside three years. As such, they are all scrambling to become API-first.

And almost all of them are going about it completely wrong.

I have run an API-first business for ten years. We were headless before it had a name. PredictHQ sits inside the production workflows of companies like Uber, Lyft, Chipotle, Domino's, and CVS, where we help AI models adapt to the real world. We deliver trusted, explainable real-world context that models learn from and act on. There is no UI in that loop, just our API improving outcomes in production.

Which means I have had ten years to make every mistake a SaaS company can make on the path to headless. I have made most of them twice. And watching the current stampede toward API-first architecture, I can tell you with high confidence what is about to go wrong.

The Mistake Underneath the Mistakes

The standard framing of "going headless" is technical. You just expose your capabilities as APIs, wrap them in an MCP server, and then you can stand back and let developers wire you into their agents.

This is looking at it completely backwards.

Headless is a distribution decision. When you go headless, you are giving up the thing that made SaaS a trillion-dollar category: the moat of the login page. The UI was never really about being a pleasing way to arrange pixels. It was the enforcement mechanism for your value — the reason customers had to come to you to get the benefit of what you built. Users had to show up to Salesforce.com or they don’t get access to your customer data. Strip that moat away, and you now have to earn your place in a world where the agent is deciding whose capability to call.

So, the question becomes what capabilities you hold on to, and which you give away. You now have to rebuild, from scratch, every mechanism of value retention that the interface used to handle: trust, explainability, switching cost, feedback loops, expansion paths, and pricing control.

Every mistake below is a place where SaaS founders, in their rush to become agent-ready, are handing away strategic power they will never get back.

Here are the six mistakes I see most often.

Mistake 1: Agents Don't Read A 40-page Quickstart Guide

For the last decade, the first commandment of getting developers to use your product was thus: thine documentation cant suck. Unfortunately, AI agents raise the bar above the standards of even the prickliest of human engineers. Agents won’t be skimming your quickstart guide every query. Instead, they need to be able to discover, reason about, and invoke your product’s capability. This needs to happen conversationally (hard) and programmatically (harder), in context, at the moment they need it. This requires what agents actually need: a way to find your capability, understand it, and call it correctly. You still need documentation, but 40 pages of instructions that come in dark mode is no longer sufficient.

Mistake 2: You handed the keys to a generic LLM and called it done

Generic LLMs are fine for simple stuff but the instant there are real decisions to be made, you have to use something customized. Anytime your product touches pricing, inventory, staffing, or security, you should not just be plugging in whatever model is popular. At first it’ll seem fine. Then your customers will start to report subtle errors that were expensive to make and expensive to find. If your capability sits anywhere near a production workflow — and if you're serious about agents, it will — then you need an LLM that knows your domain cold. General intelligence is a commodity. Domain-accurate inference at decision time is not.

Mistake 3: You shipped an MCP connector and assumed discoverability would follow

An MCP tool that no agent knows to call is a capability that doesn't exist. In the old world, you could buy your way into discoverability. In the agent world, discoverability is determined by what's in the system prompt, what's in the model's training data, and what gets recommended by tech you don't control. This is a fundamentally different distribution problem. The early movers (the ones who get embedded into agent frameworks, referenced in orchestration defaults, and trained into the models that matter) will be extraordinarily hard to displace. We highlight this at PredictHQ by asking Claude about what was happening at a location. Without our MCP, the answer came back plausible but wrong. It surfaced events 30 miles away, missed most of what was actually happening nearby, and had no way to assess predicted attendance or local economic impact. Both answers looked right. That's what makes it a problem at scale.

Mistake 4: You removed the interface but kept none of the intelligence

A key benefit to the UI first era was user data. You could track everything and then adjust accordingly. When you go headless, you lose all of that unless you deliberately rebuild it. You want to avoid the trap of shipping the API, watching the call volume go up, and assuming things are working. Meanwhile, the agent is quietly making bad calls, customers are quietly losing trust, and nobody knows why because no one instrumented the loop. When we built Bolt— our AI native developer environment—rather than build extra features, we built tools that tell us how developers are actually using our technology, where they're getting stuck, and when they want a human back in the loop. This is not because I get particularly enthralled by dashboards or anything (lord knows every SaaS founder could use less of them in their lives). It was because without that signal, you are flying blind inside someone else's system. In production AI, the feedback mechanism is the moat. If you can't observe what your capability is doing inside someone else's agent, you can't improve it. And if you can't improve it, you will eventually be replaced by someone who can.

Mistake 5: Don't be too cautious with your MCP server

One mistake we made early on with our MCP server was being overly cautious, exposing only a limited subset of our API functionality rather than opening it up fully. The reasoning at the time made sense: LLMs weren't quite trustworthy enough to hand them the keys to our full API capabilities. But AI has exploded the number of surfaces where technology can be deployed, and that changes the calculus entirely. The companies that win the agentic layer will be the ones whose capabilities are already there when an agent reaches for them.

Today's baseline models are more than capable of handling broad API access responsibly. And as long as you control the unique technology, data, security, and discoverability underlying your capability, there's little reason to stay narrow. If we were starting again, we'd have been bolder from day one.

Mistake 6: API design discipline. Don't paint yourself into a corner

The more pragmatic mistake, and one we see constantly as a business that consumes thousands of APIs and data sources, is poor API design discipline. Once an API is public, breaking changes are hugely disruptive to your customers, your integrations, and your own team. You can add to an API, but removing or changing existing behavior erodes trust fast.

The opposite failure is just as costly: creating a sprawling surface with different endpoints for every edge case until the API becomes a mirror of your internal architecture rather than a clean contract for your customers. Both paths lead to the same place, a system that's hard to extend, hard to maintain, and hard to build on confidently.

The lesson: be deliberate about what you expose, design it well upfront, and treat your public API as something close to sacred. It is your most important interface now.

Avoiding these common mistakes, rebuilding your mechanisms for trust, explainability, discoverability and value retention and you will earn your place in the AI revolution.