The age of AI is firmly upon us — and as more teams adopt artificial intelligence and agentic flows, providers are increasingly finding that their old strategies and approaches need to shift. One area where this is rapidly becoming a concern is in the domain of developer portals.

Developer portals were built around a very specific set of assumptions — a human developer arrives, reads the documentation, maybe copies a code snippet or generates a key, and then they start calling endpoints. But in this new agentic reality, that assumption is no longer universally true — in fact, AI agents are beginning to consume and adopt APIs directly without significant browsing, documentation ingestion, or sandboxing. This is not an emerging issue — it’s a present one, with Gartner predicting the AI agent-to-human developer ratio in sales is set to surge to 10:1 by 2028.

Today, we’ll look at how developer portals are evolving for this new modality. We’ll look at some best practices — including self-serve access, agentic onboarding, and contextual routing — and we’ll also consider what standards like Model Context Protocol (MCP) solve (and do not solve) in this new paradigm.

What the Traditional Developer Portal Was Actually For

To understand what changes developers should expect to the developer portal, we should first talk about what purpose the traditional developer portal actually served. A mature developer portal traditionally served various functional purposes:

• An API catalog where the API’s components could be documented, presenting a routing opportunity for users coming into the ecosystem from outside
• A documentation warehouse where all of the APIs’ functions, caveats, drawbacks, and capabilities were documented
• A sandbox for interactive testing where API calls could be developed, tested, and deployed
• A home for self-serve key generation and management
• An analytics platform for usage, with context around metering and limits for connected clients, users, and services
• A governance engine that helped inform usage limitations and expectations

Developer portals could be all of these or just a few of these, but generally, the canonical examples present these functions quite well. Stripe is well known for its developer portal, presenting documentation-first methods for users to engage, understand, and model their use. Twilio is another very good example, with its multi-language code samples and clear governance guidelines.

These portals weren’t always public either — in some cases, they were internal platforms, such as Spotify’s Backstage portal, which aggregates API documentation, service endpoints, and governance policies at scale.

But all of this was built with a simple assumption — that there was a human engaging with it. All of the code explanations, the interactive sandboxes, the visual dashboards — it was all built to be human-facing. This ultimately meant that these portals were designed for skimming or parsing by human users seeking specific answers — and were seldom designed for machine parsing or discovery.

And to be clear, this was not a poor design choice. The developer portal was perhaps the most sophisticated welcome mat the tech industry could have built. But in today’s agentic landscape, the next arrival to that mat might not be able to read the sign on the door.

How Agents Are Changing Everything

The simple fact is that agents don’t onboard the way humans do. They discover capabilities at runtime, call APIs programmatically as needed for a specific task, and have no patience for systems designed to create semantic understanding for human users.

Conversely, a human developer reads documentation, builds mental models, and then writes code. Humans are very good at making semantic models for long-term understanding, and then inferring based on that model. An AI agent — acting on behalf of a user or as part of a multi-agent system — is not very good at this, and as such, it needs machine-readable capability descriptions it can leverage and reason over at the moment of use. In essence, this is a shift to some sort of just-in-time strategy, and that shift is in fundamental conflict with the way we’ve been doing things.

To put this issue into clearer context, IDC predicts that by 2027, agent use among the world’s largest enterprises will increase tenfold. Twilio is already hedging its bets, saying, “these agents don’t browse dashboards — they need a machine-readable way to provision the full stack..” So what does this actually look like in practice, and how can we get there without ruining our developer-centric tooling of today?

What an AI-Native Portal Looks Like

Luckily, we can look to the nature of agents themselves to see what an AI-native portal would actually look like. Agents need structured data — they need a semantically linked and hypermedia-rich layer to understand how things are built, what they can do, what they can’t do, and what the agent should do when this information isn’t discoverable or inferable.

Structured Semantic Descriptions

With this in mind, there are a few core functions that modern developer portals need to do in order to be ready for agentic consumption. Firstly, every single endpoint needs to have structured semantic descriptions. We’re not talking marketing fluff or flowery detailing — instead, you should treat your portal as a sort of encyclopedia for agents, where specific functions can be mapped to tools and flows can be planned using documented pathways.

Documentation of Common Flows

Additionally, your portal should document workflows and systems in context. Don’t just document endpoints or make items available via MCP — show what they can do in concert with each other and what developers can expect when leveraging multiple systems in orchestration. Call sequencing is a big part of agentic flows, so getting this right will help agents do their work in the best possible way.

Well-Described MCP Servers

MCP servers are also very helpful tools in this process, but you need to make sure the MCP server is actually serving good data. Just offering tools is pointless unless those tools have descriptors and demonstrations. The same is true of data sources — unless you document what data is actually being offered, all you’re doing is forwarding data.

Optimize for Runtime Discovery

Discovery should be another prime focus for developer portals. This is where the old and new models diverge most significantly — human discovery is search-driven and context-dependent. Agentic discovery, on the other hand, is runtime-oriented and semantically rich. Agents must be able to follow the breadcrumbs, querying available tools dynamically at the moment of need and then following the trail to additional functions, documentation, or examples.

Don’t Throw Away Developer Experience

It’s very important to remember throughout this process that we’re not replacing the human layer. Instead, we’re repositioning and augmenting it — the portal is still serving human developers who want to browse, test, and onboard APIs manually. What we’re really doing is adding a layer on top for agents specifically — a layer that allows machine readability as an artifact of design, not as a second thought.

Are Developer Portals Still Necessary Given MCP?

The obvious question for anyone experienced working with agents is going to be simple: doesn’t MCP solve this? The short answer is no, but it’s worth working through why.

If agents can discover and invoke APIs through a structured protocol, without ever visiting a documentation site, what is the portal for? It would seem like MCP is the perfect tool for the job — and while it is a very good tool, the reality is it only covers a small subset of what we need it to cover.

MCP often wraps existing APIs and provides connective tissue for discovery, which is exactly what we want. What it does not do is replace the governance, analytics, access management, onboarding, and lifecycle infrastructure the developer portal provides. MCP adds an AI-facing capability layer — but agents need all of those other resources as well, and it fundamentally cannot replace the platform that manages what gets exposed, to whom, and under what conditions.

Put it this way: MCP is to agentic consumption what a phone book is to landlines. It’s a structured layer, but that layer still requires a supportive apparatus to form itself, let alone secure itself and its constituent parts. MCP doesn’t replace the portal — in fact, it makes the portal even more important. A portal without machine-readable outputs, semantic metadata, and agent-facing discovery mechanisms is increasingly difficult to justify — but MCP without connective tissue is just a list of endpoints.

The Future of Developer Portals

So here’s the core thesis of this piece — the developer portal is not going away, but it’s going to have to change in significant ways if it’s going to stay useful and relevant. Portals need to be less like a documentation site and more like a governed capability registry which serves both humans and machine consumers simultaneously, because that’s the reality developer portals face.

This is a complex convergence of factors — portals are becoming the management layer for a two-audience world. The human interface remains important for onboarding, exploration, and governance visibility, but the machine interface — MCP servers, detailed workflows, and well-known discovery endpoints — must become a first-class output.

Any team can generate an MCP server from an OpenAPI file. The harder problem is managing what gets exposed, enforcing least-privilege delegation, tracking lifecycles, and maintaining audit trails across multi-agent workflows. That is portal-level work — and it’s not getting any less important.

Simply put, the portals that are going to matter in three years are the ones being redesigned today — not as better documentation sites, but as the governance layer for an API economy where the majority of consumers are agents, not humans. The portals that can pivot to support both will thrive — the others that stubbornly reject either will find their usefulness and relevance diminish significantly.