Why Developer Portals Must Evolve in the AI Agent Age

Kristopher Sandoval · rss · 2026-09-22 source ↗ Reader 🖥️

Agent Governance (Internal)Agent-Native Design Agent Tool Management API Products & Sprawl MCP (Model Context Protocol)

The developer portal is not obsolete but must evolve from a human-facing documentation site into a governed capability registry that serves both human developers and AI agents as first-class consumers, because MCP provides a discovery/invocation layer but not the governance, analytics, and lifecycle infrastructure a portal supplies.

practical · expository — An advisory piece: it argues developer portals should be redesigned in specific ways (structured semantic descriptions, documented workflows, MCP servers, runtime discovery) rather than merely explaining what portals are.

Structure

Part	Role
What the traditional developer portal was for (API catalog, docs warehouse, sandbox, key management, analytics, governance engine)	context
How agents consume APIs differently from humans (runtime discovery vs. semantic mental-model building; no patience for browsing)	evidence/motivation
What an AI-native portal needs: structured semantic descriptions, documented flows, well-described MCP servers, optimized runtime discovery	prescription
Does MCP make portals unnecessary? — argued no: MCP is a discovery/invocation layer, not a governance/analytics/lifecycle layer	counterargument rebuttal
Conclusion: portals become 'governed capability registries' serving both audiences simultaneously	conclusion

Key terms

developer portal
A platform combining API catalog, documentation, sandbox, key management, analytics, and governance — traditionally built for a single human-facing audience, now being repositioned to also serve machine (agent) consumers.
governed capability registry
The author's proposed end-state for the developer portal: a registry that exposes machine-readable capability descriptions under governance, analytics, and lifecycle management, serving both humans and agents.
runtime discovery
The mode by which agents find and invoke capabilities at the moment of need, querying dynamically rather than pre-reading documentation, in contrast to human search-driven, context-dependent discovery.

Propositions

explicitTraditional developer portals were designed entirely around human behaviors (reading, skimming, sandbox testing, dashboard interpretation) and are seldom built for machine parsing or discovery.conf: high
supportsBuilding API Products in the AI Era · p5 — The earlier document's claim that internal APIs need their own developer portals is directly reinforced by this document's argument for why the portal layer persists even with MCP available.
explicitAI agents discover and invoke API capabilities at runtime rather than building durable semantic mental models the way human developers do.conf: high
explicitMCP (Model Context Protocol) provides a discovery/invocation layer for agents but does not replace the governance, analytics, access-management, onboarding, and lifecycle infrastructure a developer portal supplies.conf: high
extendsBuilding API Products in the AI Era · p1 — Both assert APIs/portals must now serve human and agent consumers simultaneously; this document extends that claim by arguing specifically that MCP alone cannot substitute for the portal's governance/analytics/lifecycle layer.
extendsGoogle and Industry Partners Announce Agentic Resource Discovery Specification for AI Agents · p2 — The ARD spec's machine-readable catalog/registry constructs are essentially the concrete protocol-level implementation of the 'governed capability registry' this document argues portals should become.
explicitPortals should not discard the human-facing layer; agent-facing machine readability should be added on top, not replace human developer experience.conf: high
implicitPortals that fail to add machine-readable, agent-facing capability layers will lose relevance as the ratio of agent-to-human API consumers rises.conf: medium

Arguments

Developer portals must be redesigned as governed capability registries serving both human and agent consumers, not replaced by MCP alone. strength: medium

Explicit premises:

Portals traditionally provided catalog, docs, sandbox, key management, analytics, and governance functions.
MCP only covers discovery/invocation connective tissue, not governance, analytics, access management, onboarding, or lifecycle management.
Agent consumption of APIs is growing rapidly (cited Gartner/IDC predictions).

Implicit premises:

Governance, analytics, and lifecycle management remain necessary regardless of how capabilities are discovered.
An organization cannot simply drop portal infrastructure once an MCP server exists, because operational/compliance needs persist independent of the discovery mechanism.
The same underlying capability surface can and should serve two structurally different consumption patterns (human browsing vs. agent runtime querying) without maintaining two disconnected systems.

Inferences:

Organizations that treat MCP server creation as sufficient ("any team can generate an MCP server from an OpenAPI file") will under-invest in the governance work the author says actually matters, and will likely face the access-control, auditing, and lifecycle problems the piece flags as unsolved by MCP alone.

Narratives

Stripe and Twilio held up as canonical examples of documentation-first developer portals; Spotify's Backstage cited as an internal-portal example aggregating documentation, service endpoints, and governance policies.
→ Establishes the baseline of what a mature (human-facing) developer portal looks like, against which the agent-native redesign is then argued.
Twilio quoted as saying its agents "don't browse dashboards — they need a machine-readable way to provision the full stack."
→ Supports the proposition that agent consumption patterns are structurally different from human browsing, using a named vendor's own framing as evidence rather than the author's assertion alone.

Questions addressed

✅ Are developer portals still necessary now that MCP exists?
No — MCP is necessary but not sufficient; portals remain necessary as the governance/analytics/lifecycle layer MCP doesn't provide.
✅ What concretely should a portal do differently to serve agents well?
Structured semantic endpoint descriptions, documented multi-call workflows, well-described (not just present) MCP servers, and runtime-oriented discovery mechanisms.
⭕ How should organizations sequence or prioritize this redesign relative to existing human-facing portal investment?

Gaps

incompleteThe piece asserts that adding machine-readable layers to portals matters increasingly but gives no case study of an organization that has actually done this (successfully or not) — no concrete before/after example of a portal's agent adoption improving after redesign.
Read next: Case studies or postmortems of specific companies redesigning developer portals for agentic consumption; vendor engineering blogs (Stripe, Twilio, Cloudflare) describing what they actually shipped rather than press/analyst framing.
incompleteNo discussion of cost or organizational tradeoffs — building and maintaining a 'governed capability registry' with structured semantic descriptions, workflow documentation, and runtime discovery is significant engineering investment, but the piece doesn't address who bears that cost or how to prioritize it against other platform work.
Read next: Platform-engineering / API-governance material on prioritization frameworks for infrastructure investment, or the corpus's existing platform-engineering-under-AI material (e.g. the InfoQ platform-engineering roundtable already in the corpus).