The rise of AI agents has transformed the way applications communicate with external services. For years, REST APIs have been the undisputed standard for integrating systems, but their design, focused on HTTP resources and methods, responds to a very different consumer: a programmatic client that executes fixed, predictable logic. With the advent of the Model Context Protocol (MCP), the consumer is now a language model that decides in real time which operations to execute, how to combine them, and how to interpret the results. This paradigm shift requires a thorough review of good API design practices. At Q2BSTUDIO, as a company specializing in custom applications, we have observed that adapting interfaces designed for humans or rigid clients to AI agent environments introduces inefficiencies and errors. This article discusses nine key principles that define the new API design for MCPs, and how companies can leverage them to build more robust and efficient solutions.
1. Design around intents, not resourcesIn REST, a typical operation aligns with a resource: create a project, list its keys, link to a repository. The client orchestrates these calls step by step. In MCP, the agent must deduce the correct sequence from the user's intent, which increases the likelihood of failure and consumes valuable context. The solution is to design tools that encapsulate a complete intent. For example, instead of exposing three endpoints to configure a project in Sentry, your MCP server offers a single create_project tool that performs the entire sequence deterministically. This approach reduces the agent's cognitive load and improves accuracy. In the development of AI for business, this abstraction is crucial so that agents can execute complex tasks without human intervention.
2. Batch operations for context efficiencyREST does not define a standard for bulk operations; Each callout creates or modifies a single element. An agent that needs to generate multiple pages, logs, or configurations will repeat the same call over and over again, duplicating arguments and increasing the context window. The solution is to offer tools that accept entire collections. Notion, for example, replaced three calls to its /pages endpoint with a single notion-create-pages tool that receives an array of pages. Not only does this save tokens, but it centralizes validation and error handling on the server. For AWS and Azure cloud service projects, where agents must provision multiple resources, batching becomes a must-have practice.
3. Consolidate closely related operationsIn REST, creating and updating the same resource are usually two different endpoints. In MCP, each tool appears in a flat menu; Having two very similar tools competes for the attention of the model and duplicates the documentation. An agent may not know whether to create or update an issue, and a unified tool (issue_write) with a method parameter resolves the ambiguity. GitHub applies this pattern on its MCP server, grouping 13 common fields under one name. This consolidation is an example of how custom software must be adapted to the needs of the consumer, in this case an AI agent.
4. Make semantics explicitREST uses HTTP status codes (401, 404) and headers to communicate results. A programmatic client knows how to interpret them. An agent, on the other hand, only sees the result of a call. A mistake like "Unauthorized" leaves too many questions open: what went wrong? Did the state change? What should the user do? The tool should return an information-rich structure, including the reason for the error, whether there were state changes, and a recovery path. For example, an order update that fails due to expired authentication should state, "The address was not updated because the session has expired. Ask the user to reconnect the account." This level of detail reduces misinterpretations of the model. At Q2BSTUDIO we integrate these patterns into our cybersecurity and automation solutions to ensure agents make informed decisions.
5. Documentation as control codeIn REST, documentation is consulted during development; Once the client is built, changes to the documentation do not affect behavior. In MCP, the agent reads the tooltip at runtime; each word influences the selection and construction of arguments. A vague description like "Find logs" leaves too much room for interpretation. A precise description specifies what logs it is looking for, how to identify the service, the time range allowed, and what it excludes (e.g., audit events). This makes documentation a critical flow control artifact. Development teams should treat changes to descriptions as code changes, subjecting them to testing. In the field of business intelligence, where agents must query heterogeneous data sources, well-designed documentation prevents invalid calls and optimizes performance.
6. Suggest next actionsHATEOAS, a REST principle that is rarely implemented, takes on new life in MCP. It consists of a tool's response including links or suggestions on what action to take next. An agent does not have a predefined plan; if the result of a Sentry trace indicates that there is an AI conversation associated with it, the server can return a structured hint to call get_ai_conversation_details with the identifiers already populated. This reduces the need for the agent to search the tool surface or infer the transition. Companies that develop AI agents can benefit greatly from this pattern to create seamless and autonomous experiences.
7. Field filtering to save contextREST often returns full representations of resources, leaving the client to extract the fields it needs. In MCP, each field returned goes into the context of the model, and if it's not relevant, it wastes tokens and can confuse the agent. Providing a field filtering parameter (similar to GraphQL projections) allows the agent to request only the data needed for the immediate decision. For example, a inspect_customer tool that accepts fields returns only the identifier, name, and risk status; the rest is out of context. This principle is especially useful in custom software applications where large volumes of data are handled.
8. Protect Destructive OperationsREST assumes that the client has already validated the operation through its user interface. In MCP, the model decides in the heat; A tooltip can instruct the agent to ask the user for explicit confirmation before deleting a file. In addition, the response must confirm the change, indicate whether there was a state modification, and provide a recovery path (such as a temporary backup). For example, the backup path and its expiration date remove_file returned. This level of protection is critical in production environments where cybersecurity and data integrity are a priority.
9. Disseminate tools progressivelyA REST API can expose hundreds of endpoints because each application selects the ones it needs during development. An agent cannot make that permanent selection; You need to know only the tools relevant to the current context. Loading all definitions at the start consumes context and adds to the confusion. Progressive disclosure consists of first exposing search tools or meta-tools that, based on the user's query, load the specific details. Stripe uses this pattern: first a stripe_api_search that identifies the method, then stripe_api_details for its parameters, and finally stripe_api_read/write to execute it. For small surfaces (less than five tools), it is not necessary; but when you handle dozens or hundreds of operations, it is essential. At Q2BSTUDIO we apply this philosophy in the design of automation systems that integrate multiple data sources and services.
Conclusion: a new design contractThe move from REST to MCP is not a simple technical migration; It's a profound shift in the way we think about interfaces. The backend may be the same, but the consumer—an AI agent—operates with dynamic logic, limited context, and without the ability to read static documentation. Each principle described here seeks to transfer to the server the intelligence that previously resided in the client's code: group intentions, batch operations, make semantics explicit and protect the user. Companies that adopt this new paradigm will not only improve the efficiency of their agents, but also reduce context and error costs. At Q2BSTUDIO, as experts in enterprise AI and business intelligence services, we help organizations redesign their APIs and processes so that AI agents can operate autonomously and securely. The future of integration is conversational, and design must evolve with it.
