Okay, I'll say it. Every time someone kicks off a new backend project and opens a browser tab for "REST API best practices," a small part of me quietly weeps into my coffee.
Not because REST is bad. REST is fine. REST has been very good to us. But we keep reaching for the same hammer without asking whether the thing we're hitting is still a nail.
It is 2025. The AI agents are not coming. They are already here, already poking at your endpoints, already confused about what your /users/search route actually does, and already making things up when your docs are not clear enough. So maybe it is time we build with that reality in mind.
Let me introduce you to MCP, and let me try to make it make sense without putting you to sleep.
What Even Is MCP
MCP stands for Model Context Protocol. It is an open standard, originally from Anthropic, that defines how AI models and agents communicate with external tools and data sources. Think of it as a universal translator between "what the AI wants to do" and "what your system can actually do."
If REST is like a menu at a restaurant, MCP is like having a chef who can look at your fridge, understand what you have, and cook something sensible without you having to explain the entire menu from scratch.
The core idea is that instead of just exposing raw HTTP endpoints and hoping whoever calls them reads the documentation, you expose structured capabilities. You tell the agent: here are the things you can do, here is what they mean, here is what goes in and what comes out. And the agent actually understands that in a way it never quite did with a Swagger doc.
The REST Problem Nobody Talks About
Here is a scenario that should feel familiar.
You have a beautiful REST API. Versioned. Documented. Rate-limited. You even have a Postman collection. You are proud of it and you should be.
Then someone builds an AI agent on top of it.
The agent hits /orders and gets back 200 records with no context. It does not know what "status: 3" means. It does not know which fields matter. It starts guessing. The guessing is confident and wrong. Someone files a bug. The bug is hilarious and also a little frightening.
This is not an API quality problem. Your API is fine. It is a context problem. REST was designed for developers who read docs and write code. It was not designed for autonomous agents that need to understand intent, not just structure.
MCP bridges that gap. Instead of "here is a JSON payload, figure it out," MCP says "here is a tool called getRecentOrders, it takes a userId and a dayRange, it returns a list of orders with human-readable status labels, and here is exactly what each field means."
That is a different conversation entirely.
So How Does MCP Actually Work
At the core, an MCP server exposes three things.
Tools are functions the AI can call. Think of them like your API endpoints but with enough context baked in that the agent knows what they are for. A tool has a name, a description in plain language, a typed input schema, and a typed output. No ambiguity. No "check the docs."
Resources are data the AI can read. Files, database records, configuration, documents. The agent can browse them and pull what is relevant to the task at hand.
Prompts are reusable templates that help the agent reason correctly. You define the shape of the interaction upfront so the AI is not reinventing the wheel every time.
Your MCP server sits next to your existing backend. It does not replace your REST API. It wraps your business logic and presents it in a way that is legible to an AI agent. Your existing endpoints can stay exactly where they are. You are just adding a smarter front door.
The Real Reason You Should Care Right Now
I have been in this industry long enough to know that "future-proofing" is usually code for "over-engineering something nobody asked for." I say this as someone who has committed that sin more than once.
But this is different, and here is why.
The tools developers use are already MCP-aware. Claude, GitHub Copilot Workspace, Cursor, and a growing list of IDEs and agent frameworks support MCP out of the box. Your developers' AI assistants are already trying to understand your codebase and your APIs. If you make your system MCP-readable, you are not preparing for some distant AI future. You are improving the experience for your team today.
When we started thinking about how AI-assisted workflow building would work, it became obvious fast that dumping our REST surface area in front of an agent and hoping for the best was not a plan. The agent needed to know what a "workflow step" meant in our domain, not just what shape the JSON had. MCP gave us the vocabulary to express that.
And once we started thinking in terms of tools and resources rather than endpoints and payloads, our API design got cleaner too. That was a nice bonus we did not expect.
How to Get Started Without Rewriting Everything
This is the part people always want, so here it is.
You do not rewrite your existing API. Please do not rewrite your existing API. You create an MCP server alongside it.
Start by picking your three or four most important capabilities. Not all of them. The ones an AI agent would actually need to help a user get something done. For a project management tool, maybe that is creating a task, listing tasks by status, and updating a task. That is it for now.
For each one, write a tool definition. Give it a name that describes intent rather than implementation. createTask beats POST /tasks. Write a description that explains what it is for, not just what it does. Include every field in the input schema with a description. Do the same for outputs.
Then wire that tool definition to the actual function in your codebase. The MCP SDK for your language of choice handles the protocol layer. You focus on the business logic.
Test it with Claude Desktop or any MCP-compatible client. Ask the agent to do something. Watch what it does. You will immediately see where your tool descriptions are confusing and where they are clear. That feedback loop is extremely fast and extremely useful.
Then iterate. Add more tools. Add resources if your agents need to browse data. Add prompts if you want to guide the agent toward correct reasoning in your domain.
A Few Things to Get Right Early
Authentication matters. MCP does not define how you authenticate, which means you need to. OAuth 2.0 works well here. Make sure your tools respect the same permission model your REST API does. An AI agent should not be able to do things a user cannot do.
Versioning matters. Your tool definitions will change as you learn more about how agents use them. Plan for that. A description rewrite is not a breaking change, but a schema change is.
Logging matters more than you think. When an agent calls your tools, you want to know what it asked for, what you returned, and how long it took. This is how you catch the weird edge cases and the occasional "why did it do that" moments.
Keep tool scope narrow. One tool should do one thing well. Resist the urge to build a mega-tool that accepts fifteen optional parameters and does different things depending on which ones you pass. That works okay for human developers who read docs. It does not work for AI agents that are trying to reason about what a tool is for.
The Bigger Idea
REST APIs were designed for a world where the consumer was a developer writing code against a known contract. That world is not going away. But a new world is sitting right next to it, where the consumer is an AI agent trying to accomplish a goal on behalf of a user.
Building MCP-ready systems is not about chasing a trend. It is about recognizing that the assumptions baked into REST do not all hold when the client is an AI. And fixing those assumptions now, while you are building, costs a fraction of what it costs to retrofit them later.
You already know this pattern. You designed your REST API for the client consuming it. Now design your MCP layer for the AI agent consuming it.
Same principle. New client.
Your future self, and your future AI colleagues, will thank you.
Mano works as Senior Development Manager and Software Architect at Cavintek, where the team builds Cflow, a workflow automation platform. He has been writing software and occasionally regretting earlier versions of it for about 13 years.
Top comments (0)