MCP Explained
mcp-explained.comThis is too dense. You might as well just post some Python code with sufficient comments to get the same point across. I think a nicely written article with a few diagrams would go a long way. Sometimes less is more.
MCPs don't really need this level of technical explanations (it's basically just a REST API with standardized endpoints for discovery aimed at agents), and AI agents really do lack in the taste dimension when it comes to these things.
Yeah, this feels like one of those ‘explainers’ that feel like they are great to someone who already knows how the system works, but don’t actually work for newbies because they tacitly assume knowledge of the shape of the system that seems ‘obvious’ to someone steeped in it.
This is a problem with most docs I encounter. _Good_ documentation should also teach the user how to use the thing, not simply end up as glorified out-of-band code comments.
I found that it's a mistake I would often make when writing documentation about something I deeply understand. I forget the questions that led me to that understanding. Now I make a conscious effort to think about the knowledge of the intended audience. I still miss things, but that's why it's good to have other people review.
> it's basically just a REST API
The opening has 1 paragraph and 5 table entries. One of them is “Not REST”
It’s a little scary that this was considered too dense or complex because the basics were explained in something that could be read in 1 minute. That still wasn’t enough to stop the top HN comment (as I write this) from calling it too dense and giving incorrect information that is immediately refuted by skimming the top part of the article.
It is not technically REST, but it is basically REST. The alternative to a server endpoint is JSON-RPC over stdin which has the same request/response format as REST. This is exactly the point about over-complicating it by saying "it's not REST, it's not JSON-RPC". It's a JSON request/response protocol with a defined format.
REST !== JSON-RPC
https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...
> It is not technically REST, but it is basically REST.
What does that even mean?
> the same request/response format as REST
What request/response format does REST have?
Do you even know what HATEOAS means?
The opening is fine, but when you click "Start the lessons" you get a six-pane interface that imho is pretty overwhelming
Yeah, I can click around and follow what's going on. But I'm with GP: this is not making it easier to understand. It's great at being Hollywood UX: looks pretty, stuff moving everywhere. One click on "step" makes the image animate, and change the text in the left sidebar, top middle, and right sidebar, in addition to stepping the table in the bottom middle. But it's almost the opposite of distilling information
> you get a six-pane interface that imho is pretty overwhelming
Agreed, and it probably doesn't need to be overwhelming but the design choices leave the intent and purpose of the UI fairly unclear. It requires a bit of clicking around to understand what it's all for, and it's quite flat and unappealing, leaving little drive to do that work.
Sign of times man. Not that long ago -- on HN mind you -- someone posted an article that landed on main page that used lsblk as some sort of secret hacker linux command.
That's the purpose of the comment, to make a comparison that's simpler than the article that is missing from the article.
If the article said, "It's basically just REST". There'd be no need to comment as such.
This is actually one of the better 'mcp explained' type 'articles' i've read.
While we’re applauding brevity, three cheers for the first line being “model context protocol”. While yes, this one is common, it’s still nice not having to scroll through 20 screens of blah to still not find out what the thing is.
> The opening has 1 paragraph and 5 table entries. One of them is “Not REST”
and yet...
It's literally JSON-RPC I'm not sure why you say it's a REST API. It's not even close to a REST API.
In this context/application I see a lot of similarities.
They both provide stateless RPC methods and human readable metadata that makes them easy to route.
You could ask why json-rpc was even necessary for 2.0. I think mostly just for stdio and backwards compatibility.
In the venn diagram of MCP and REST, there is an (optional) overlap for sure but one does not subsume the other.
> This is too dense.
Maybe it was written for an AI? :)
Or by an AI? Or both?
To me the writing itself seems pretty economical.
From your comment, I expected to be annoyed by a bunch of slop or obscurities.
My guess is the writing did not come straight out of an LLM and was carefully curated.
If I’m wrong I’d love to have the style prompt.
The way I explained MCP is browsing Chrome to the event stream URL then pinging the server with cURL
These vibe code explainers look nice on the surface but actually make things even more confusing. There's an element of curating which information to present and when that doesn't come across here.
Agree. These LLM-generated explainers tend to be useful only to the person who prompted for that explainer. That person knows what's unclear to them, they have their internal mind model that is known only to them and they can refine the explainer to their liking and keep prompting until it looks the way they want it to look and explains concepts how they want them explained. I use these all the time but see no reason for sharing something that is a couple prompts away for anyone else.
I appreciate it, just started getting into 'vibe' coding converting some non arm (mac) apps into arm and it's pretty magical on this 128gb m5 max, a little slow but it can run deepseek flash 1017 pretty well.
Watched a few youtube apps about a 'harness' and I still haven't dived too deep into it but using openchamber to work with the code is awesome. Next step is MCP to various apps and seeing what it can do.
Are MCP calls composable in e.g. codex yet? e.g. can a model pipe a jira MCP call to grep or sed, or at least into a file? Last I looked at MCP it was just a vastly worse version of curl, .netrc, and some short text files describing calls (which are themselves greppable). Is there anything useful beyond that that I'm missing?
Last I checked it still doesn't. A skill that tells your client to call a CLI, and uses the help menus for progressive disclosure, benchmarks better. Developers noticed this immediately and there is sort of an anti-MCP sentiment. The protocol was probably largely conceived for non-coding agents run by non-coders.
In theory the agents could just natively know how to do this better, to get exactly the composability you want. In fact, you could probably just write a CLI mcp-caller and tell the agent to only call MCPs via that, and boom you're done.
Where MCP does come back into the picture even for coders is a more controlled way to break a sandbox.
What I will also say is it matters less and less. It's the usual bitter lesson. The models are just getting so much better all attempts to optimize everything are a drop in the bucket.
Too much exposure to local coding assistants seems to lead developers to assume that all agents typically operate in an environment where they have a full shell, with the ability to write arbitrary python scripts and curl commands and execute them.
Consider an agent which doesn’t have those tools though. MCPs are a great way to give them constrained access to remote resources.
It's more that I'd immediately ask why they don't. Obviously having some interpreter is going to make the model much more capable of context management and just analysis, so at the very least, it should be able to pipe MCP calls into e.g. a python interpreter with no IO other than stdin/stdout.
Yes, they are. Look into CodeMode (available in both Opencode and Pi). The agent has access to a code execution tool that can call and compose other tools/MCPs by writing code.
Yeah, the new Pi harness has codemode and I imagine there's many more.
Internally at my startup, I built an interpreter for a subset of Javascript where the agent can compose its tools and MCPs. The cool thing about it is that it can create durable workflows and automations from these same scripts.
pi harness composes them just fine if you're specific about what you want to do.
"Find the latest prod JIRAs and analyze the related logs"
Anyone using MCP? Seems like it's a dead end compared to CLIs and normal APIs.
It's not like it really brings anything to the table that was missing or even needed.
I mentally group it with XML at this stage. Useless bloat peddled by people trying to sell something to people who don't really understand it much. Sort of thing I expect IBM to turn up and sell some Websphere Enterprise MCP Router Platform or something.
I used it for a project with okay results. The point was to share our org's data in an accessible yet very flexible manner via Claude. The idea is that the MCP server provides structured, reliable means of querying and then presenting the data in predictable and useful ways, with a bunch of checks and balances along the way.
It was possible without MCP, but arguably this convention made the whole thing a bit more reliable and consistent. It also provides some safe guards against how people might get this data alternatively. People can now ask "What was the ocean acidity like for January 2016 to March 2017 in the Salish Sea? And Claude will reliably draw up a graph for all stations in the Salish Sea monitoring this parameter, report which values have or have not been QC'd, show a map of the stations' locations, etc.
It works better than a skill or plugin. It allows me to integrate a protected endpoint more easily for the end users. It only knows about read-only endpoints. No risk of people handing credentials to Claude to make it easier. Overall it makes it pretty seamless to bundle a bunch of domain knowledge into the server, providing access and empowerment to a team of scientists who can but would really prefer not to write API queries when they have one-off questions about our data.
It could also be done with a CLI or something, but, the goal is to provide a powerful interface using simpler tools. An API or CLI would defeat the purpose.
Have you considered that maybe it’s useful bloat that you don’t understand much?
XML has features that other documents don’t support and thus can be useful in some domains.
Likewise, I find MCP extremely useful for accessing enterprise systems using OAuth. It’s secure, easy to define access controls, and easy to audit.
Yeah but what does MCP actually offer that the agent can't just do on its own? I work with APIs and Oauth and gRPC and all the rest all day long and I've never thought "gee I need another spec so my agent knows how to call this API". The agents just work it out like an engineer does. MCP just seems pointless it doesn't seem to add anything except more token consumption and complexity
The best thing about MCP is its almost impossible to use for most people except developers. Therefore ensuring our existence.
Don't believe me? Try connecting Blender to Codex.
The lightly technical people I talk to have no problems getting it done.
Their secret, which is not very secret, is to ask the AI to help them set it up.
I think this might follow that bell curve meme where people on the unsophisticated and highly sophisticated ends of the curve are leveraging the LLM for MCP setup (and other routine tasks) while some in the middle are making it more complicated than it needs to be because they still think of it as outside the domain of AI-assisted work.
The biggest problem I see isn’t getting MCP set up, it’s people getting stuck using the wrong tools for the job. I’ve improved a lot of workflows by observing what someone is doing and suggesting a better tool for the job.
I feel like I'm living in a different world than other people with my MCP experiences.
At my job we maintain an MCP for our admin portal/prod data and it's seen a lot of use. Our admin side was a mess to use so allowing admins to ask questions about prod data has been a huge help for everyone.
And for myself personally, connecting MCPs to Claude has also been an insanely huge productivity boost. It's really nice to just ask for a link to Datadog when I want to monitor some change I made, instead of trying to craft a query myself.
Multiple non-developer colleagues at my workplace are trying out all kinds of MCP connectors in their Claude instances. Maybe when MCP was mostly relegated to coding harnesses it was more of a developer's tool but things have changed a lot.
Also, Apple just announced their preview for new Siri AI capabilities and part of that is they seemingly are going to add MCP to apps (if developers of the apps want to) as tools, which would enable Siri to use functions of apps, similarly to Claude Desktop using functions of services through MCP tool calls.
MCP honestly seems like something thrown in there to keep devs relevant.
Just like us to take something and limit it back to being useless until we implement the feature (tools).
The real "race to market" winners will just throw the credentials into the SQL connector and let 'er rip like a real man.
> The real "race to market" winners will just throw the credentials into the SQL connector and let 'er rip like a real man.
That's what we started doing... and never looked back. Now we're thinking of exposing parts of the database in readonly mode to in-house staff (non-developers) so they can vibe code whatever the hell kind of tools they want...
I agree - MCP just standardizes APIs to make it easier for LLM clients to consume them. Imagine if we had to use standard APIs - it would be more difficult to enable any single one. That’s why the labs instituted MCP.
> MCP just standardizes APIs
No it doesn't. It adds yet another Nth "API standardization" spec.
You might be right. I created a quick and dirty MCP server to expose my existing REST API calls. It doesn't work as well as I hoped. The AI client seems to have trouble determining the mix of MCP tools needed to fulfill a user's prompt, unless a specific tool is defined for that request. Maybe I am missing something.
A “flaw” (if you will) of MCP is that some developers with a REST api background naively think it is similar and add tools for each discrete thing to be done. They also tend to put guidance for the LLMs in the description of each tool.
Now a Claude/Codex/etc user installs a few MCP servers and before they know it their context is already largely used up with tool schemas and guidance before they’ve sent their first prompt.
In response to this harnesses aggressively “hide” most of this to agents, so the agents land up doing best guesses on how to use tools, doing things like sending wrong argument names, etc.
Turns out that a really effective strategy to deal with this is to make two tools only, one to execute a script (eg in JS) and another on how to get guidance on how to craft a script.
When an agent needs to use the tool, they look at the “help” and then craft JavaScript (something they’re already very good at). If the execute endpoint returns adequately descriptive errors with stack traces then the agent can pretty much always self fix their mistake.
We worked this out for ourselves in our own product and we found out after that Cloudflare wrote a blog post on how they use the same strategy.
> Don't believe me? Try connecting Blender to Codex.
Is it that bad? I have Blender connected to Claude (and my mind is quite blown by how great it is to use) and it was quite easy if you could follow the tutorial (the hardest part was reading that you have to click on something twice)
it's becoming pretty mainstream, lots of (ordinary, non-dev) people connecting google docs/slides, notion, linear etc to their claude or cowork
The site is beautifully made and I see a point but as many of others are also noticing, picking a beginner up, taking maybe 10 steps with him to introduce all of the concepts and terminology could be better for everyone to understand.
I couldn't find a github link, if anyone knows where to find the code for this, I'd like to modify it to make it a primer more friendly to non-technical managers.
Literally just give the link to Claude/GPT/etc. and it'll be able to replicate it easily. Hell, just loosely describe this as a text prompt and they'll probably nail it one shot. This is basically the "default" interactive explainer one-pager that all of these models generate.
LOL, its early, if I'd thought for 5 seconds I would have realized that. thank you.
it's a single page html file, just download it and use as input for what you want to do
"Local or remote subprocess or URL" is doing a lot of heavy lifting
MCP is that kind of thing a manager comes up to you with and says "ARE WE USING MCP? it's the latest thing" and you roll your eyes, hunch over, stare at your screen and say to yourself "no, we're using strings, just strings." as you watch them drift to their next prey, you see scrawled up in their hands a note with crossed out acronyms. NFT. Web3. AMP. SOAP. IoT.
The manager is asking because marketing and sales are asking. They want to put a bullet-point on the feature list of the brochure. The best play is to build a compliance feature that's firewalled into a corner where it can't hurt anything. The product technically includes MCP, NFT, et al.
mcp's are barely needed, good cli's are usually better
For coding agents I agree with you, but people are building for more than just developers now. The idea that a user facing service would give their agents shell access is kind of horrifying, as you then make it possible for prompt injection to mean a system take over.
MCP has its place. It should not be the default for many use cases, but if you need to expose specific tools in a secure way to agents that are not trusted to run shell commands then MCP is great. Developers need to think beyond their own use cases and consider architecture patterns if they're going to build, not just consume, AI systems.
100% agree. I've been building MCPs that enable Claude (my agent of choice to have voice conversations with). These hook into my home maintenance system (https://homemaintlist.com) and workout tracking system (https://tallyup.codewalkers.net) plus several private mcp servers I've made to expose Claude to specific services. These all allow me to just have conversations with Claude and have all these very specific things available and take action on them.
Curious how you talk to Claude? I have some automations set up but I feel locked into Gemini on android if I want to be able to use a wakeword (e.g. while driving). I use Claude for non-voice but haven't found a convenient way to start up a chat with Claude.
Yeah...wish there was a better way than just opening the app and clicking the voice button. I haven't found one. My talking is usually in the car, so it's not too inconvenient for me to do that.
I see, yeah that works when I know I'll be in a situation for a while where I may want the option to say something or going over something like verbal brainstorming but I find I am much more often having a random thought and want to capture it right away without pulling out my phone or interrupting what I'm doing.
Can only hope google relaxes their limitations on choice of ai assistant. In the meantime I'm setting up a raspi with openwakeword to just act as an interface for voice to voice interactions for while I'm home.
Completely agree, MCP is going to be a continuing topic for providing capabilities to LLMs for non-technical users. If you're in a tightly regulated enterprise environment asking your IT admin to enable CompanyX's MCP Connector in Claude is much more palatable than asking for a CLI tool to be installed as well.
It's about where the agent runs more than the users - hooking e.g. Datadog's Bits AI up with access to relevant repos in my company's GitHub org to find out what's driving the metrics its looking at likely wouldn't be a thing if not for GitHub's MCP server and OAuth, I doubt whoever admins that would bother if Datadog had to set up some completely custom thing.
Excellent points. We still need to employ good cybersecurity principles when granting AI access to tools and resources. Let’s not throw out everything learned in the last three decades. Keep the access narrow in scope and targeted.
I do agree with you and was not aware of those reasons before, thanks for clarifying.
fwiw, I’ve only done cli tools for agents to install in their own sandboxes, not access on remote machines.
This was just to avoid MCP infra, but the newer stateless protocol makes that much more trivial.
I find it depends a lot on the model used and what the MCP does. I have agents trawl research papers, and just giving the raw API to DeepSeek leads to lots of wasted tokens and bad use of the API options. Here, wrapping the API to minimize the available options and providing sane defaults fixes that. Perhaps a frontier model can use the API directly without issues, but for DeepSeek a good MCP wrapper is very useful. Besides that, having control and limits in the MCP is very useful for some ratelimited APIs
I agree. MCPs have the massive problem of not being composable, which is a big strength of shells/CLIs allow.
People make the argument that it doesn't matter for non-programmers. I use Bluebeam (a pdf editor which is standard in the construction industry) daily, and it has an MCP, but a big problem is that if the agent wants to import or export a large amount of data from a document, then it has to regurgitate a bunch of tokens into or out of the MCP. If it were a CLI, then it would just pipe things in and out as it needs.
I ended up just having the agent make a script that wraps the MCP so it can use it as a CLI instead.
> MCPs have the massive problem of not being composable, which is a big strength of shells/CLIs allow
Tool calls being composable or not are a property of the harness being used, not of MCP servers
As a trivial counterpoint, streaming outputs and proper signaling support is required for being able to compose efficiently under any setup/harness. The more layers of abstractions you add, the more likely it is your MCP server didn't support the usecase that some later agent came up with and so you can't stop your stream when you find your top 3 hits. If you don't even own the server, you can't even modify the source and restart it to fix it.
There are usecases of MCPs (e.g. serving outside customers via proprietary tools), but composability has not been in the minds of the early users of MCP and it is one of the hundreds of little practical drawbacks they have when used in house.
It just removes the need to install a cli tool on your local machine. I in general are sceptical before I install some external 3rd party software. With MCP over HTTP transport, the MCP might still talk to your agent and tell the agent to do XYZ, but your agent can still treat that command as malicious and refuse to execute. While not perfect, it is just another layer of security.
It is the same with a wepapp: You could argue you don't neex browser apps if the user just install a software on their computer, but we feel better using the sandboxing environment of your browser.
Depending on use case, would start with just solid HTTP APIs, then a simple CLI to consume them, then add MCP using the new spec. Build slowly only adding new access protocols as needed.
Be surprised how far apps can get with just solid & well documented APIs. Modern agents are smart!
My suggestion is to just let the HTTP client itself be the MCP server.
Then you don't need an MCP server per service anymore, you just need one and a whitelist of authorized services.
MCPs with oauth have a better security story
not this tired discusssion again
I saw RunLayer at AGNTCon. Good concept.
It's almost 2027 and I still dont understand if we actually need MCP. I must admit I am not really surfing the AI wave. But looks like a nothing burger.
Think of MCP like CORBA and COM+ and all those other systems.
The same reasons those were needed is why this is needed.
I've been thinking alot about developer education and while I think this format is fun to fiddle with, I feel this(and a lot of technical learning resources) are no longer as valuable as they would have been in a world without LLMS. Now if I wanna learn something I ask claude and I can essentially build my knowledge incrementally, have it build animations iteratively, ask questions and essentially derive an understanding.
Too dense. I’m not sure how this was outlined to the LLM but please first educate yourself on the basic principles of teaching, learning, and education. The AI that made this went off the rails and it is borderline incomprehensible.
My take away from this overview is that MCP is just a synonym for JSON RPC.
This is noisy slop that doesn't explain anything. Maybe try starting with a definition and a single diagram?
I swear when I see stuff like this is makes me depressed about the future of our industry. Pick up an Edward Tufte book or something and use your brain
Yep. This is what we get when people that didn't study UX and product development have access to AI. They have good ideas, ask AI to generate it and can't see that the result is unbearable.
Everyday we get a new AI slop dashboard posted here
Horribly designed
Want to be more specific?
Well for the step by step I cant keep up woth the looping speed and cant go back
AI slop sorry
For me it's just:
from mcp.server.fastmcp import FastMCP
For me it’s just
“Claude add an mcp for this”
AI Slop
Do you really need to know how this plumbing works? I'd just tell the AI how to use a tool, and to write the MCP spec if it is really ever needed.