When an organization introduces MCP, how does the way it structures its MCP servers shape the developer portal?
An organization introducing MCP has an architectural decision to make about the scope of its MCP servers. A server might provide access across a company or business unit, follow the boundaries of an API product, or sit closer to an individual service. Each choice has implications for what needs to be organized, documented, and made discoverable through the developer portal.
The MCP server provides the interface through which AI clients interact with the capabilities exposed to them. Around that interface sits the organizational context: how a capability relates to existing APIs and API products, who owns it, how it should be used, and what governance applies. For organizations that already use a developer portal to organize their API landscape, MCP introduces another interface that needs to fit into that structure.
This article examines three useful implementation patterns—organization-level, product-level, and service-level—and the developer portal publishing approaches associated with each. The choice between them may follow existing API ownership and product boundaries, the degree of autonomy given to individual teams, and governance or regulatory requirements. The patterns are not a maturity model or a ranking; they describe different ways of deciding the scope of an MCP server and organizing the capabilities around it.
The three core MCP implementation patterns
Across current enterprise implementations, three broad architectural patterns appear repeatedly. These patterns organize MCP servers at different levels of the architecture: the enterprise, the product domain, or the individual service. That organizational choice shapes governance, discoverability, and the way those capabilities are presented through the developer portal. Understanding these patterns provides the foundation for designing an effective developer portal information architecture.
MCP pattern 1: Organization-level
Setting up MCP as an interface to the organization or department, an organization deploys a single, centralized MCP server that acts as a comprehensive entry point for all capabilities across the entire company or a major business unit. This architecture exposes the enterprise API landscape through a single MCP interface.
From the perspective of the developer portal, this pattern presents the organization as a single catalog of AI capabilities.
- Best Suited For: Startups, SMBs, tightly integrated enterprise business units, or centralized platform teams with strict governance requirements.
- Key Benefits: Provides a single point of connection for AI agents, streamlines single sign-on (SSO) and central OAuth token exchange, simplifies governance, and minimizes client-side connection management.
- Challenges: Centralized ownership may create coordination bottlenecks if multiple teams must rely on a single team’s release and governance process to add, modify, or retire capabilities exposed through a shared MCP server. As the capability catalog grows, clients should support progressive tool discovery and selection so that only relevant tool definitions and schemas enter the model context, reducing token use, latency, and tool-selection complexity.
MCP pattern 2: Product-level
A domain oriented, product-level MCP architecture applies Domain-Driven Design (DDD) to AI tooling. Instead of bundling the entire enterprise into a single server or splitting it down to individual endpoints, APIs are grouped into cohesive, domain-specific product bundles. Each product domain exposes its own dedicated MCP server, for example such as 'Payments & Billing,' 'Customer Identity,' or 'Logistics & Order Management'.
The developer portal will mirror the organization’s API product model, with MCP capabilities grouped by business domain.
- Best Suited For: Mid-to-large enterprises with established API Product Managers and domain-based team ownership.
- Key Benefits: Aligns perfectly with API productization strategy. Product managers retain authority over their domain's tool definitions, resources, and prompt templates, while developers interact with logical, business-oriented toolsets. The boundary of the MCP server becomes a natural context boundary in which to operate (e.g. ordering, transactions,...)
- Challenges: Requires cross-functional coordination between API product owners and developer portal architects to maintain consistent metadata and security conventions across products.
MCP pattern 3: Service-level
When we apply the individual endpoint pattern, MCP is treated as a lightweight, decentralized sidecar or protocol translation layer for every individual API endpoint or microservice. Each standalone API service publishes its own lightweight MCP server wrapper.
The portal becomes the primary mechanism for organizing and relating a large number of independently managed MCP capabilities.
- Best Suited For: Large enterprise environments running highly decoupled, composable microservice architectures with distributed engineering teams.
- Key Benefits: Maximum operational agility. Engineering teams can deploy, update, version, and sunset MCP endpoints independently without central deployment bottlenecks.
- Challenges: Requires sophisticated client-side orchestration and MCP server discovery, typically supported by MCP registries, alongside a well-structured developer portal catalog that keeps those capabilities connected to the wider enterprise landscape. When you can’t rely on the boundary of the MCP server as a constraint for the intended use context, this needs to be otherwise communicated, enforced, and validated.
Information architecture is the backbone of developer portal design. When introducing MCP, the information architecture of the portal must address two distinct discovery models: human navigation (browsing and reading) and machine discovery (AI agents querying tools, schemas, and URI resources). Using flexible content management frameworks like Drupal (which powers many of the world's leading enterprise developer portals) we can implement these strategies cleanly and cost-effectively.
Architectural mapping: MCP patterns and matching publishing strategy
| MCP pattern | Information architecture approach | Drupal portal implementation |
|---|---|---|
| Organization-level (pattern 1) | Global platform feature (central hub) | Dedicated top-level landing page, global authentication docs, consolidated schema registry. |
| Product-level (pattern 2) | Integrated API product catalog (multi-protocol bundle) | Extend API product content types with MCP fields, multi-protocol tabs (REST, GraphQL, MCP), domain-level auth |
| Service-level (pattern 3) | Granular component catalog (composable entities) | Dedicated MCP card/entity types linked to underlying REST/gRPC endpoints, dynamic search tags |
Publishing pattern 1: dedicated enterprise AI hub
In organization-level MCP setups, publishing connection details only within individual API reference pages scatters information that belongs to a shared runtime and would make the overall entry point harder to discover. Instead, the portal IA should elevate MCP to a top-level navigation item (for example an '/ai-hub' or 'Connect to AI'). This landing page serves as the single source of truth for authenticating LLM hosts, configuring base connection URIs, and viewing the global catalog of tools available under the central server.
Publishing pattern 2: multi-protocol API product catalogs
For product-level MCP deployments, the developer portal mirrors the API product model. MCP server documentation sits alongside the existing API documentation for the same product, allowing developers to evaluate all supported interfaces in one place. In Drupal-based portals, this is achieved by extending the API Product entity model. A developer viewing a product like 'Customer Insights API' can navigate between REST documentation, GraphQL schemas, and an MCP Server definition within the same product. This unifies the developer experience, making AI capability discovery a natural extension of existing product evaluation.
Publishing pattern 3: composable MCP entity cards and dynamic catalogs
If we choose service-level MCP setups, the portal requires a highly modular entity model. Each service-level MCP server is published as its own catalog entity: a discrete entity card within the global catalog. Those entries cross-reference the underlying API documentation while documenting the tools exposed by the server (discoverable through tools/list), their associated schemas, and any human-in-the-loop (HITL) safety requirements. Developers can filter catalog views specifically for 'MCP-enabled' APIs/endpoints.
Enterprise capability organization: what exactly belongs in the portal?
MCP specifies how servers expose capabilities and how clients interact with them. Around that sits another set of questions: where people find the appropriate capability, how they get connected, where permissions and lifecycle are explained, and how APIs and MCP interfaces are organized together.
We found it useful to separate those responsibilities. The division shown here describes a practical enterprise architecture, not boundaries prescribed by the MCP specification. Depending on the platform and implementation, some responsibilities may be shared across the developer portal, API management platform, gateway, registry, and MCP server.
| Concern | Organizational layer: developer portal responsibility | Runtime layer: provided by the API platform or MCP server |
|---|---|---|
|
Discovery and evaluation |
||
| Capability discovery | Help consumers discover enterprise capabilities and understand the available ways to consume them, through navigation, search, taxonomy, and business context. | Individual APIs and MCP servers expose capabilities, but do not organize the enterprise landscape. |
| Capability context | Explain ownership, business purpose, relationships, intended audience, and preferred consumption patterns. | Outside the scope of the runtime protocol. |
| Understanding what the server offers | Explain the business purpose of the capability, how it relates to other capabilities, and when this particular interface is the appropriate way to consume it. | Expose tools, resources, and prompts through the MCP protocol. |
|
Using capabilities: |
||
| Getting connected | Explain prerequisites, supported clients, authentication, connection details, and provide quick starts. | Expose the endpoint and support the chosen transport (streamable HTTP or stdio) and applicable authentication mechanism. |
| First successful interaction | Guide users through their first API call or tool invocation and help troubleshoot common issues. | Execute requests and return results according to the protocol. |
| Reference documentation | Present schemas, examples, usage guidance, and related documentation in a navigable way. | Expose protocol-defined metadata for tools, resources, and prompts, including tool schemas where applicable. |
| Permissions and trust | Explain authentication, delegated permissions, trust boundaries, and approval requirements where applicable. | Apply authorization requirements and runtime security controls. |
|
Long-term management: |
||
| Lifecycle and governance | Document ownership, service lifecycle, versioning, deprecation, operational guidance, and governance policies. | Apply runtime policies, protocol/version behaviour and operational controls. |
| Information architecture | Organize APIs, products, MCP servers, and related content into a coherent, discoverable experience that reflects the organization’s operating model. | Outside the scope of the runtime protocol. |
The emerging Agent Plugins specification (in v0.9 Draft as of 2026-08-17) adds another layer to this picture by providing a portable way to package Agent Skills and MCP server configurations for compatible clients. Its scope is deliberately narrow: packaging remains separate from discovery, distribution, permissions, trust, and user experience. For developer portal teams, that leaves the questions discussed here largely unchanged: how these capabilities are organized, documented, governed, and presented within the enterprise.
Documenting trust, permissions, and tool behavior
What additional information does a developer portal need to publish once APIs are exposed through MCP?
Publishing MCP involves more than exposing another endpoint. It also means documenting the operational characteristics that allow both people and AI agents to use those interfaces safely and predictably.
Tool behavior and trust boundaries
Some MCP tools have side effects, such as initiating a payment or modifying data, while others provide read-only access. Those differences should be visible in the developer portal. The MCP specification includes guidance around trust, user consent, and security boundaries, including Human-in-the-Loop (HITL) workflows. Where user confirmation is required before a tool executes, the portal should communicate that expectation alongside the tool documentation.
OpenAPI-to-MCP schema translation
Organizations can derive MCP tool definitions from existing OpenAPI descriptions as part of the API delivery pipeline. The developer portal should present the resulting MCP metadata alongside the original API documentation while keeping both representations aligned as the APIs evolve.
Authentication and scope mapping
A single MCP connection may expose tools with different authorization requirements. The developer portal should make those relationships explicit by documenting how OAuth2 scopes or delegated permissions map to individual MCP tools, helping developers understand what an AI client is authorized to invoke on a user’s behalf.
Organizations make different trade-offs
The architectural and publishing patterns described above are already appearing in enterprise implementations. While organizations make different trade-offs, the relationship between MCP architecture and developer portal structure is becoming easier to observe in practice.
One recurring architectural discussion concerns pattern 3, where each API or microservice exposes its own MCP server: does this constitute an anti-pattern due to client-side connection bloat? Critics of that pattern point to the growing number of client connections and the orchestration required to manage them. Teams operating large microservice environments can reach a different conclusion because they need operational velocity. When paired with an intelligent client orchestrator or an API gateway adapter layer, the decentralized ownership allows them to deploy, version, and govern MCP interfaces independently, and they may decide to accept the additional client-side coordination complexities as a trade-off befitting their existing API layer operating model.
Example: MCP architectural pattern 1 in practice
A different trade-off can be seen in organizations that adopt Pattern 1 and expose a single, centralized MCP server. This approach is often chosen when AI teams need a consistent interface across a broad set of existing systems and data sources. Rather than exposing individual MCP servers for each underlying service, the centralized server becomes a controlled entry point that aggregates capabilities behind a single authentication, governance, and security model. That architectural choice is typically reflected in the developer portal. Instead of documenting many independent MCP servers, the portal presents a single entry point, with onboarding guides, authentication flows, capability documentation, and examples organized around the centralized server. The underlying APIs, services, and ownership boundaries remain, but they are no longer the primary entry point for AI clients.
While every organization will arrive at a different implementation pattern, the underlying preparation is remarkably similar. The following roadmap focuses on the capabilities a developer portal should develop, regardless of which MCP architecture is ultimately adopted.
Strategic roadmap: prepare your developer portal for the agentic era
Based on the implementation patterns discussed above, the following roadmap provides a practical starting point for preparing an existing developer portal.
- Audit existing API assets
Identify which APIs are highest-value targets for AI integration and determine whether your organization favors centralized gateway control (pattern 1), product-domain governance (pattern 2), or microservice autonomy (pattern 3). - Modernize portal content models
Extend your developer portal CMS content types (e.g., in Drupal) to support MCP primitives (tools, resources, and prompt templates) alongside existing OAS files. - Establish clear governance and safety docs
Define guidelines for human-in-the-loop approvals, OAuth scope mapping, and rate limiting specifically tailored for AI agent consumers. - Measure and iterate
Track both human developer traffic and machine agent invocations across your portal to continuously refine information architecture and discovery paths.
Conclusion
Developer portals have long helped people make sense of an organization’s digital capabilities, often through APIs and API products. AI systems become another class of client interacting with those capabilities, through MCP servers. That changes what needs to be described and how capabilities are organized, without fundamentally changing the role of the organizational layer around them.
The implementation patterns in this article arrive at three different architectural choices. Some organizations expose a single enterprise MCP server, others organize around API products, and others follow the boundaries of individual services. Those decisions then naturally shape the information architecture of the developer portal, from the way capabilities are grouped and documented to how governance, authentication, and trust boundaries are communicated.
From that perspective, MCP introduces another way of exposing and consuming enterprise capabilities. Protocols, interface styles, and consumption patterns will continue to evolve. The need to organize capabilities, relate them to one another, and provide the context needed to understand and use them remains.
Working out where MCP fits in your existing API landscape?
If your organization is introducing MCP alongside an existing API portfolio, we can help map how those capabilities relate to your API products, business solutions, and the information your customers and partners already encounter. Our Solution Discovery Pilot identifies gaps in that structure and provides a prioritized roadmap before you invest in new catalogs, portal structures, or larger redesigns.
