Designing an MCP server from a REST API without tool sprawl

At a glance

What this is: This guide explains how to design an MCP server from a REST API by grouping endpoints into agent workflows, resources, and prompts, rather than exposing a tool per endpoint.

Why it matters: IAM and identity teams building AI-connected services need to curate what agents can call, because poor MCP design expands both operational noise and the identity surface that must be governed.

👉 Read WorkOS's guide to designing an MCP server from a REST API

Context

Model Context Protocol changes the design question from "what endpoints do I have" to "what does the agent need to do". A REST API is built for developers who integrate once and reuse code, while an MCP server is built for an LLM agent that has limited context, no durable memory of the API, and no debugger. In identity terms, that shifts the governance problem from static API exposure to runtime interaction design for agentic access.

The article's core warning is that a one-to-one wrapper strategy usually creates tool sprawl, fragmented context, and poor task completion. For teams managing NHI, agentic AI, or hybrid identity programmes, the lesson is the same: every exposed capability becomes part of the access model, so the interface itself must be curated as carefully as the credentials behind it.

Key questions

Q: How should security teams design MCP server access for AI agents?

A: Security teams should design MCP access around a small set of agent goals, not a mirrored list of REST endpoints. Group related backend calls into workflows, expose known data as resources, and reserve tools for actions that truly change state. That keeps the agent oriented, reduces context churn, and makes the access surface easier to review and govern.

Q: Why do REST endpoint wrappers fail when used as MCP tools?

A: They fail because REST and MCP serve different interaction models. A one-to-one wrapper floods the agent with too many choices, too much intermediate JSON, and too many steps to complete simple tasks. The backend may still work, but the agent loses context and produces noisy, unreliable behaviour that is harder to audit.

Q: What do teams get wrong about tools versus resources in MCP?

A: Teams often treat HTTP verbs as the deciding factor, but the real question is whether the model is fetching context or doing work. A known object such as a plan, profile, or inventory usually belongs in a resource, while a search, update, or workflow belongs in a tool. That distinction materially changes the agent's reliability.

Q: How should organisations govern MCP servers in identity programmes?

A: Organisations should inventory MCP servers like any other machine-facing access layer, then recertify exposed capabilities, remove unused tools, and keep state-changing actions tightly scoped. The goal is to reduce what an agent can even see as callable. That is a governance control, not just a software design preference.

Technical breakdown

MCP is not a thin REST wrapper

REST and MCP optimise for different consumers. REST expects a human developer to read docs, write code, and debug once, while MCP expects an LLM agent to choose among tools in real time with a limited context window. That means every extra tool description, response payload, and intermediate call increases cognitive load for the model. A server that mirrors every endpoint one-for-one technically works, but it often fails as an interface because the agent has to reconstruct the workflow across too many steps. The practical design task is to reduce call count and context growth without hiding necessary capability.

Practical implication: Prune exposed functions to the smallest set of agent-complete workflows, not the largest set of API endpoints.

Tools, resources, and prompts solve different access patterns

Tools are for actions the model decides to perform, resources are for data the model reads as context, and prompts are reusable workflows that a user or agent invokes intentionally. That distinction matters because it changes how the model reasons. A search query can behave like a tool, even if the underlying API uses GET, while a known object such as a recipe, pantry state, or meal plan often fits better as a resource. Prompts are useful when a task has a standard sequence the model should follow, such as a repeatable planning flow. The design choice is semantic, not HTTP-based.

Practical implication: Classify each capability by intent and data shape before exposing it, then map only stable context to resources.

Granularity determines whether the agent can stay oriented

The article argues for N-to-1 and 1-to-N design decisions instead of mechanical endpoint mirroring. Multiple endpoints may belong inside one agent workflow, such as planning meals by combining pantry data, preferences, recipe search, and meal-plan creation. Conversely, one generic endpoint may need to be split into multiple tools when it serves distinct user intents. Tool parameters and return objects should also stay flat and compact, because deeply nested schemas and oversized JSON responses make the agent less reliable. The underlying mechanism is context management: every field competes for attention.

Practical implication: Collapse multi-step user goals into a few coarse-grained tools, and split overloaded endpoints when intent becomes ambiguous.

Breaches seen in the wild

• Moltbook AI agent keys breach — Moltbook breach exposed 1.5M AI agent keys.
• AI LLM hijack breach — attackers used stolen AWS access keys to hijack Anthropic LLM models on Bedrock.

Read our 52 NHI Breaches Analysis report for a comprehensive view of breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Tool sprawl is the MCP equivalent of uncontrolled entitlement growth. A one-endpoint, one-tool design looks complete, but it creates a large, noisy action surface that an agent must repeatedly navigate. That is not just a usability issue. It is an identity governance issue, because every exposed tool becomes an access decision the model has to make under context pressure. The result is weaker task reliability and a harder-to-audit runtime surface. Practitioners should treat tool inventory as governed exposure, not as a coding convenience.

Context-window pressure is a governance constraint, not just a UX limitation. MCP tools, descriptions, and intermediate outputs all consume conversational state, which means poorly curated servers can fail even when the backend API is sound. This is the same failure mode that appears when identity systems expose too many choices to the wrong actor at the wrong time. The named concept here is identity blast radius through interface design: each additional callable capability expands the amount of trust the agent must carry. Practitioners should recognize that interface shape directly influences security outcomes.

Least privilege for agents starts with capability curation, not endpoint enumeration. The article's core design advice aligns with OWASP NHI thinking because the issue is not whether an endpoint exists, but whether the agent should ever see it as callable. Resources, prompts, and coarse-grained tools create different trust boundaries, and those boundaries are part of the security model. A server that exposes only the workflows an agent can safely complete is easier to govern than one that advertises everything and hopes the model chooses well. Practitioners should design for constrained intent, not exhaustive exposure.

Good MCP design is lifecycle governance for machine access. Once you think of MCP as a user interface for an agent, the familiar IAM questions return in a new form: what is exposed, what is hidden, what is read-only, and what can change state. The article shows that these are not implementation details. They are governance decisions about how a machine identity is allowed to interact with business systems. That means server design, access design, and operational review belong in the same conversation. Practitioners should review MCP exposure the same way they review privileged application access.

From our research:

• 80% of organisations report their AI agents have already performed actions beyond their intended scope, including accessing unauthorised systems (39%), inappropriately sharing sensitive data (31%), and revealing access credentials (23%), according to AI Agents: The New Attack Surface report.
• Only 44% of organisations have implemented any policies to govern AI agents, even though 92% agree governance is critical to enterprise security.
• That policy gap is why teams should also review the OWASP Top 10 for Agentic Applications as they tighten MCP exposure and tool design.

What this signals

Identity blast radius through interface design: as MCP adoption grows, the security question shifts from "can the backend be called" to "what does the agent perceive as callable". When 80% of organisations already report AI agents acting beyond intended scope, the governance gap is not hypothetical. It is a design problem that needs inventory discipline, capability review, and tighter mapping between intent and exposure.

The reader should expect MCP server review to become part of broader machine-identity governance, especially where agent workflows touch sensitive business systems. The practical signal is clear: resource scoping, tool curation, and prompt design will increasingly sit alongside credential control and access review as one continuous control plane. Teams that separate those concerns will miss how agent behaviour actually expands risk.

MCP servers also make agentic policy failures easier to observe because the interface itself reveals whether the organisation has over-exposed actions or under-scoped context. That is why design choices around granularity matter. A server with fewer, better-formed workflows gives security teams a sharper audit line than a server with dozens of thin wrappers.

For practitioners

• Curate agent-facing workflows before exposing endpoints Start from the top five agent tasks, then map only the minimum set of tools, resources, and prompts needed to complete them. Treat every exposed function as a governed capability, not a convenience wrapper. Use the same review discipline you would apply to high-risk NHI access, especially where a single tool could chain into multiple backend actions.
• Convert read-only context into resources Expose known objects such as current state, records, or summaries as resources when the agent is fetching context rather than performing an action. That reduces tool chatter and makes the server easier to reason about during access review. For broader agent design guidance, compare this pattern with the OWASP Agentic AI Top 10 and the OWASP NHI Top 10.
• Collapse multi-step intents into coarse-grained tools If a user goal requires several backend calls, bundle those calls into one workflow tool so the agent does not have to manage the sequence itself. Keep return payloads short and structured so the model can preserve state without flooding the conversation. For a deeper architectural walkthrough, see Analysis of Claude Code Security.
• Review exposed MCP capabilities as part of privileged access governance Add MCP servers to the same inventory, recertification, and offboarding processes used for other machine identities. Remove tools that are never needed by agents, and confirm that read-only resources cannot trigger state changes indirectly. That creates a cleaner audit boundary for machine-to-system access.

Key takeaways

• MCP server design is an identity problem as much as a developer experience problem, because every exposed tool becomes part of the agent's trusted action surface.
• The strongest design pattern is to curate around agent goals, then map data to resources and actions to coarse-grained tools instead of mirroring REST endpoints.
• Teams that govern MCP exposure as machine access control will have a far better chance of keeping agent behaviour inside intended scope.

Key terms

• Mcp Server: A server that exposes tools, resources, and prompts to an LLM agent through the Model Context Protocol. In practice, it is a governed interface layer that shapes what the agent can see, read, and do, so its design directly affects reliability, auditability, and access scope.
• Tool Granularity: The level of task size and responsibility assigned to a single callable action. In MCP, coarse-grained tools often work better than thin endpoint wrappers because they reduce context churn and keep the agent focused on outcomes rather than intermediate API mechanics.
• Resource: A piece of information the agent reads for context rather than acting upon. Resources are usually stable, addressable objects such as a current plan, record, or inventory, and they help keep the conversational state smaller and more predictable.
• Prompt Workflow: A reusable instruction pattern that starts a structured sequence for the agent to follow. Unlike a tool, it is not primarily about state change. It is useful when the task has a standard shape and the user is intentionally selecting a known operating procedure.

Deepen your knowledge

MCP server design and agent-facing access control are covered in the NHI Foundation Level course, the industry's only accredited NHI security programme. If you are building machine-facing interfaces from a REST API, it is a strong fit for your governance baseline.

This post draws on content published by WorkOS: Designing an MCP server from a REST API. Read the original.