Developer portals were built for humans — agents need them more

An AI coding agent inherits the same confusion a new engineer faces on day one: which services exist, who owns them, what deployment patterns are approved, which databases are sanctioned, and where the security boundaries live. The difference is that the new engineer asks a colleague, reads a wiki, and slowly accumulates tribal knowledge over weeks. The agent makes decisions in seconds — with whatever context it has at inference time. If that context is incomplete, ungoverned, or stale, the agent produces code that compiles, passes tests, and violates architectural constraints nobody documented in a place the agent could reach. Developer portals for agents solve this by turning the internal developer portal (IDP) from a browser-based convenience layer into programmatic infrastructure that agents query before acting.

Agents inherit the same confusion humans had — faster

Internal developer portals emerged because platform teams recognized a pattern: engineers wasted hours discovering service ownership, deployment paths, approved libraries, and infrastructure boundaries that existed only in tribal knowledge or scattered wikis. The IDP codified that knowledge into a browsable catalog with service ownership, golden paths, scorecards, and documentation tied to living systems.

AI agents face the same information gap but with higher stakes. A human developer who cannot find the approved database connection pattern asks a colleague before proceeding. An agent that cannot find it invents one — often a plausible-looking implementation that bypasses connection pooling, ignores retry policies, or creates a direct dependency on an internal service without going through the gateway.

The portal is not optional for agents. It is the difference between governed automation and confident hallucination. Without structured, queryable platform metadata, agents operate on whatever context fits in their prompt — and that context rarely includes the organizational constraints that make code production-safe.

Service catalogs become tool catalogs for agents

The first evolution is structural. A service catalog that answers "what services exist and who owns them?" must also answer "what can an agent invoke, under what constraints, and through which interface?" This transforms the catalog from a reference for humans into a tool registry for machines.

Through protocols like the Model Context Protocol (MCP), the service catalog becomes programmatically accessible. An agent asks "who owns payments?" and receives a structured response: the owning team, the approved API surface, the authentication mechanism, the rate limits, and the escalation path for incidents. No human opened a browser tab. No context was hallucinated.

The machine-readable catalog requires:

• Service metadata — ownership, tier (critical/standard/experimental), dependencies, and API contract version.
• Capability declarations — what the service exposes as invokable tools, with parameter schemas and permission requirements.
• Constraint annotations — what an agent is not allowed to do with this service, expressed as machine-enforceable policies rather than prose warnings.
• Freshness guarantees — whether the metadata reflects live state or a snapshot, and how stale the snapshot is.

The portal that serves this data to agents is not a different product than the one that serves humans. It is the same source of truth with a programmatic access layer on top — MCP servers, llms.txt manifests, or structured API endpoints that agents consume without rendering HTML.

Golden paths become executable constraints

Golden paths — the opinionated, pre-approved patterns for common tasks like creating a service, deploying to production, or connecting to a database — have always been the IDP's highest-leverage feature. For humans, they reduce decision fatigue. For agents, they serve a different function: they define the boundary of safe action.

An agent that proposes a new service without querying the golden path might generate a reasonable Dockerfile, a plausible CI pipeline, and a functional Terraform module. All of it could be wrong — wrong base image, wrong deployment target, missing observability hooks, no cost guardrails, no security policy compliance. The golden path encodes all of these constraints in a template the agent consumes before generating anything.

The shift is from discoverable golden paths (humans browse and choose) to executable golden paths (agents query and follow). The platform team defines the constraint; the agent operates within it. When the constraint is violated, the platform rejects the action at the boundary — not after merge, not after deploy, but at the moment the agent proposes a change that contradicts the approved pattern.

This is where developer portals for agents intersect with blast radius management for AI coding agents. The portal defines what an agent is allowed to know and do. The blast radius controls define how much damage an agent can cause when it acts outside those boundaries.

Scorecards should feed AI review, not just human dashboards

Most IDPs include scorecards — maturity assessments that grade services on documentation coverage, test coverage, dependency freshness, security posture, and operational readiness. These scorecards traditionally serve human audiences: engineering managers reviewing platform health, teams identifying tech debt priorities.

For agents, scorecards serve a different purpose. They become pre-merge validation signals. An AI-generated pull request that introduces a new database dependency can be automatically checked against the scorecard: does this service already meet the data access pattern standard? Is the dependency on the approved list? Does the proposed change degrade the service's compliance score?

The scorecard-to-review pipeline requires:

• Machine-readable scoring criteria — not prose descriptions of "good" and "bad" but structured rules an automated system can evaluate.
• Real-time score computation — the scorecard must reflect current state, not last week's snapshot, because the agent's PR is evaluated against the live standard.
• Actionable feedback — when a score drops, the system must return the specific constraint that was violated and the approved alternative, not a generic "score decreased" message.

Organizations that define operational runbooks for production AI agents already have the muscle for this: translating organizational knowledge into structured, machine-executable procedures. The scorecard pipeline is the same discipline applied to code quality governance.

The portal is a product, not a wiki

The distinction matters for platform teams building agent-aware IDPs. A wiki is a collection of pages that humans maintain and agents scrape. A product is a governed system with an API contract, access control, versioning, observability, and SLAs.

When the IDP serves agents, it inherits product-grade requirements:

• Access control — not every agent should see every service. Permission scoping determines what context an agent receives based on its role, the repository it operates in, and the action it is attempting.
• Versioning — when the golden path changes, agents consuming the old version need either graceful deprecation or forced migration. The portal must track which version each agent consumed.
• Observability — which agents queried which catalog entries, how often, and what actions followed. This telemetry is essential for understanding how AI interacts with platform infrastructure and where governance gaps exist.
• Latency guarantees — an agent blocked on a catalog query during code generation adds seconds to every interaction. The portal must serve responses at API-grade latency, not wiki-grade page-load times.
• Feedback loops — when an agent proposes something the platform rejects, the rejection reason must flow back to the agent as structured context for its next attempt, not as a generic error.

Platform teams that treat the IDP as a wiki will find agents ignoring it in favor of whatever context is faster to access — typically the codebase itself, which contains patterns but not constraints.

Should MCP catalogs replace developer portals for agents?

The convergence of MCP and IDPs raises practical questions about architecture and ownership.

Do agents need MCP servers or a full internal developer portal?

MCP servers expose tools, resources, and prompts through a standardized protocol. An IDP provides the organizational context that gives those tools meaning: ownership, policies, dependencies, approval status, and compliance state. MCP is the transport layer; the IDP is the data layer. Agents need both — MCP to invoke capabilities, the IDP to know which capabilities are sanctioned and under what constraints.

Should every service in the catalog be agent-accessible?

Not necessarily. Some services carry sensitivity levels that require human-in-the-loop approval before any interaction. The IDP should declare which services are agent-invokable, which are agent-readable but not invokable, and which are invisible to agents entirely. This tiered visibility model prevents agents from discovering — and attempting to use — systems they should not touch.

How should platform teams measure whether the portal serves agents effectively?

Track three metrics: agent query volume (are agents actually using the portal?), constraint violation rate at merge time (are agents following golden paths?), and scorecard drift after agent-generated PRs (does AI-generated code maintain or degrade service quality?). If agents bypass the portal because queries are slow or incomplete, the portal is failing its second audience.

The opposing view: agents can read code and docs directly

A common argument holds that sufficiently capable agents do not need a curated portal. They can read the codebase, infer patterns from existing implementations, parse documentation from READMEs and inline comments, and derive organizational norms from code review history. Building a separate governance layer adds platform complexity without proportional value.

The argument holds for individual coding tasks in well-structured repositories with strong conventions. It breaks at organizational scale. Inferring which database pattern is approved requires reading every service that connects to a database and identifying the modal pattern — which may differ from the correct pattern. Inferring service ownership from git blame misses organizational changes. Inferring deployment constraints from existing pipelines misses the constraints that exist precisely because nobody has violated them yet. The portal encodes intent, not just current state. Agents that infer from code read what exists. Agents that query the portal read what is allowed.

Key takeaways

• AI agents face the same information gap as new engineers — service ownership, deployment paths, approved patterns — but make decisions in seconds without the safety net of asking a colleague.
• The internal developer portal must serve two audiences: humans through a browser, and agents through programmatic protocols like MCP.
• Service catalogs evolve into tool registries with capability declarations, constraint annotations, and permission requirements — not just ownership records.
• Golden paths shift from discoverable templates to executable constraints that agents query before generating code.
• Scorecards become pre-merge validation signals, not just dashboard metrics — rejecting AI-generated PRs that violate platform standards at the boundary.
• The IDP is a product with API-grade requirements: access control, versioning, observability, latency, and structured feedback loops.

Conclusion

The internal developer portal is becoming the agent control plane — the system that determines what an AI agent is allowed to know, which tools it can invoke, and which constraints it must obey. Platform teams that built IDPs to reduce human confusion now face a second, more demanding audience: agents that cannot ask clarifying questions, cannot exercise judgment about ambiguous guidance, and cannot self-correct when they violate an undocumented norm. The portal that serves this audience is not a wiki with an MCP wrapper. It is a governed product with machine-readable policies, real-time state, and enforcement at the boundary. The organizations that build it will scale AI safely. The ones that skip it will scale AI's mistakes.