I have in the past cribbed about how terrible most LLMs are in tool-calling and my dislike for being dependent on frontier models to see fair performance of tool-calling accuracy. I found that I am not alone here and that many in community building AI Agents, echoes this pain, from time to time. But I am might aware that this whole Gen-AI tech is still very raw and amateur in terms of its adoption and understanding, no matter how loud the noise is - think of it as the side-effect of virality. So I grokked more, experimented more, tinkered more breaking down the problem to see how much of my understanding is right/wrong. It took a good number of iterations to have my aha-moments that smaller LLMs too can do more than a decent job at tool calling without custom training and too much of prompt engineering. The other big aha moment that stuck me is how much different designing APIs for MCP is from that of REST paradigm. The rest of the post is all about the key lessons on this, just so you aptly design your APIs for MCP Server so as to see great mileage of your LLM Agent on tool calling accuracy metrics.
So MCP isn't just a wrapper around REST APIs for LLM Agents to integrate with third-party systems. So having a one-to-one mapping between APIs of your MCP server with that of the REST server is an overkill. Here is my catch-phrase for you to have in your mind to get your API design for MCP server right:
REST (REpresentational State Transfer) APIs are abstractions of domain modeling for human consumption.
MCP (Model Context Protocol) APIs are abstractions of human intent for agent consumption.
Let me elaborate on this based on my bad experience before I got things right for me and I bet it should help you too to get productive at work.
1. REST APIs are abstractions of domain modeling for human consumption.
- Abstractions of Domain Modeling: The core activity in designing a REST API is to model your business domain into "resources" (nouns like /users, /orders, /products). These resources and their relationships form a map of the problem space. The HTTP verbs (GET, POST, PUT, DELETE) are the uniform interface to manipulate these resources.
- For Human Consumption: REST APIs are designed to be understood by human developers. A developer reads the API documentation, understands the resource model, and writes code to navigate that model, compose requests, and handle responses. The success of a REST API is measured by how intuitively a developer can grasp and use it.
- Documentation Driven: Humans rely on the documentation (like Swagger or OpenAPI) to understand what resources are available, what data they contain, and how to interact with them. Without this documentation, it's hard for a human to navigate the API.
- Analogy: A REST API is like a well-organized library with clearly labeled shelves and books. A developer knows how to navigate the library and find the specific information they need.
In essence, when we design REST API, we ask, "How can we structurally represent our business domain so that a programmer can easily tell a computer what to do with it?"
2. MCP (Model Context Protocol) APIs are abstractions of human intent for agent consumption.
- Abstractions of Human Intent: Instead of exposing a fixed model of resources and actions, MCP is designed to capture a human user's goal or intent. The user (or an agent on their behalf) expresses a desire ("find tomorrow's weather in Chennai," "reserve two movie tickets for noon show tomorrow for any available Telugu movie", "list out blogs authored on the topic Gen AI from my blog"), not a specific API call.
- For Agent Consumption: MCP is not designed for humans to call directly (unless you would like to test it, like I do using unit tests and manual testing using some tool). It's designed for AI agents (like an LLM inside a code editor) to call. The agent's job is to translate the user's natural language intent into a series of operations against "tools" or "resources" provided by the MCP server. The protocol standardizes how these tools are discovered and invoked.
- Documentation and Prompt Driven: LLM Agents too rely on the API documentation and might additionally be served with pre-defined prompts to serve it better. The "documentation" for an agent is not a lengthy guide for a human developer, but a machine-readable specification (like an OpenAPI schema) of the tool's purpose, parameters, and return types. This is the essential information an LLM needs to know what a tool is and how to use it. Also, an LLM's understanding isn't static and it can be enhanced with dynamic, contextual prompts from the MCP server. This allows the system to guide the LLM's reasoning and tool selection in real-time, making the agent more effective and precise. Check out my project in HuggingFace demonstrating this dynamic prompt calling.
- Analogy: An MCP API is like a remote control with clearly labeled buttons for specific functions (e.g., search_flights, book_hotel). The agent, knowing its goal, just needs to press the right button without caring about the inner workings of the device.
- REST says: "Here is my data model. Learn how to navigate it and build what you need."
- MCP says: "What do you want to do? I will give you a simple, executable function to do that."