Welcome back to My Weird Prompts. This is episode one thousand eight hundred and eighty, and today we are doing another Talk Through The Docs session. If you are new to this format, this is where Herman and I take a long, hard look at technical documentation so you do not have to. We pull out the highlights, find the parts that are actually going to trip you up in production, and try to make sense of the architecture. Today, we are diving into the Model Context Protocol, or MCP. You can find these docs at model context protocol dot info slash docs.
It is great to be here, Corn. Before we start, I want to note for the record that we scraped these specific documents on April third, twenty twenty six, at twelve forty UTC. Since these are living documents, things move fast. If you are listening to this a few months from now, please go check the live site because the specifications and the SDKs are evolving literally every week.
Right, so check the live version if you are following along. Now, Herman, give me the high level here. The docs use this phrase over and over: the U S B C for AI. That is a pretty bold claim for a protocol. What are they actually trying to solve?
It is a classic N times M integration problem. Right now, if you build a new AI tool, say a specialized database or a new calendar API, you have to write a custom integration for every single AI platform. You write one for Claude, one for OpenAI, one for Gemini, one for your IDE. It is a mess. MCP flips that. It provides a universal interface. You write one MCP server for your data, and then any MCP client, like the Claude Desktop app or a specialized coding tool, can instantly talk to it. The docs describe it as the H T T P for AI context integration.
I love that analogy because H T T P changed everything by being vendor neutral. But looking at page two of the docs, they break this down into a three tier model: Hosts, Clients, and Servers. This is where I think people might get confused. In a normal web world, the client and the host are usually the same thing, like your browser. How does MCP split those up?
That is a great catch and it is a technical nuance that matters. In the MCP world, the Host is the big application that the user is actually touching, like Claude Desktop or a development environment. The Client is the specific implementation of the protocol inside that host that manages the connection. Then the Server is the capability provider. It is the thing that actually knows how to read your local files or query your Postgres database. The design principles here are really focused on security first and vendor neutrality. They want this to work regardless of which large language model is sitting behind the curtain.
Okay, so if I am an enterprise architect looking at this, the benefit is that I do not get locked into one vendor. I can build my internal data connectors once and they stay useful even if we switch from one model provider to another. But let's get into the guts of it. Page ten of the docs talks about the four core capabilities. They call these the vocabulary of MCP: Tools, Resources, Prompts, and Sampling. Herman, let's break these down because I think people use the words tools and resources interchangeably in common conversation, but the protocol is very specific here.
They are very distinct in the spec. Tools are actions. These are functions that the model can call. But the docs are very clear: tools require user approval. If a tool says move this file to the trash, the client has to ask the user for a thumbs up. Resources, on the other hand, are data. Think of them like a read only file system or an A P I response. It is context that the model can pull in to understand the world. If you want the model to see your database schema, that is a resource. If you want it to execute a query, that is a tool.
That makes sense. What about Prompts? The docs say these are pre written templates. Is that just a fancy way of saying saved system instructions?
Essentially, yes. It is reusable prompt engineering. Instead of you having to figure out the best way to ask an AI to summarize a legal document every time, the server can provide a template called legal summary that is already optimized. It standardizes the workflow. But the one that really caught my eye is the fourth one: Sampling. This is fascinating. Sampling allows a server to turn around and ask the model for a completion.
Wait, so the server, which is supposed to be the helper, can ask the brain for help?
It enables recursive workflows. Imagine a server that is supposed to categorize your emails. It pulls the email, but it is not sure what category it fits. It can use the Sampling capability to ask the main model, hey, based on this text, is this a receipt or an invite? It allows for much more complex agentic behavior where the tools themselves are semi intelligent.
That sounds powerful, but also like a loop that could get expensive if you are not careful. Before we get into the heavy developer stuff, the docs have this five minute quickstart on page eight. They claim you can give Claude Desktop the ability to manage your files in five minutes. I tried this, Herman, and it is impressive, but it is also a bit terrifying. You basically edit a J S O N file on your computer and suddenly the AI has a hammer icon in the UI.
The hammer icon is the big visual indicator. If you see that, it means MCP tools are active. The quickstart has you use a filesystem server via an N P X command. For those who do not know, N P X is a tool that comes with Node dot J S that lets you run packages without manually installing them first. You point Claude to your desktop folder, and suddenly you can say, hey Claude, organize my downloads folder by file type, and it just does it.
The security part is what I want to highlight from the docs there. It explicitly says that servers run locally. This is why it is mostly for desktop hosts right now. The AI is not reaching into your computer from the cloud; your local desktop app is running a local process that has permission to touch your files. But here is the gotcha I found in the troubleshooting section: the configuration file for Claude Desktop requires absolute paths. If you try to use a relative path like dot slash my folder, it will fail silently and you will spend an hour wondering why the hammer icon is gone.
That is a classic developer trap. Always use the full path from the root. Another thing the docs mention in that quickstart is that your first server response can take up to thirty seconds. Do not panic and kill the process. There is some initialization overhead the first time the server spins up and the model maps out the available tools.
Let's talk about the learning path. This was on page three, and I have to say, I wish more protocols did this. They laid out four levels from Zero to Hero with time estimates. Level one is understanding, level two is using, level three is building, and level four is mastering. They estimate level three, building your own custom server, takes four to six hours. Herman, you have built these. Is that estimate realistic?
If you are comfortable with TypeScript or Python, four hours is plenty of time to get a basic server running. The SDKs are very clean. But what makes the docs special here is the self assessment checklist. They do not just give you a tutorial; they tell you what you should be able to explain before you move to the next level. If you cannot explain the difference between a host and a client, the docs tell you to stay in level one. It is very structured.
It feels like they are aiming for enterprise adoption, not just hobbyists. Which brings us to page six: the Java S D K and the Spring AI integration. This was a surprise to me. Usually, these new AI protocols are all about Python and maybe a little bit of Node. But seeing a first class Java S D K with Spring Boot starters? That tells me they want this inside big corporate backend systems.
The Spring AI integration is very slick. They have this at Tool annotation. If you are a Java developer, you just annotate a method in your Spring bean, and the MCP server automatically registers it as a tool. You do not have to write the J S O N schema manually; the S D K reflects on your code and generates the documentation for the model. It handles the sync and async implementations for you. This is clearly targeted at people who want to put AI agents on top of legacy enterprise data without rewriting everything in Python.
But there is a big constraint we have to mention. The docs are very honest about this on page ten. Right now, this is a local only game for the most part. They say remote hosts are in active development. Herman, how much of a deal breaker is that?
It depends on your use case. For a developer tool or a local assistant, it is fine. It is actually a security feature. Your data stays on your machine. But if you are trying to build a multi user web app where the cloud model needs to reach back into a user's private network, you have to wait or build your own bridge. The current transport layer defaults to S T D I O, which means the host and the server talk via standard input and output. It is very simple and very secure because it is just two processes on one machine. They do have a version called S S E, which is Server Sent Events, for web based apps, but the docs definitely lean toward the local execution model for now.
I noticed another gotcha in the troubleshooting section for Linux users. It says Claude for Desktop is not available on Linux. So if you are on a Linux machine, you either have to use a community workaround or build your own client using the Python or Node tutorials. The docs provide the code for a minimal viable client, but you are going to be doing more heavy lifting than a Mac or Windows user who just gets an app.
That is true. But the docs also point you to the MCP Inspector. If you are building a server, you do not actually need Claude to test it. There is a dedicated debugging tool that lets you interact with your server, call tools, and see the raw J S O N messages. It is essential for development because it takes the "black box" of the LLM out of the equation so you can see if your code is actually working.
Let's wrap up with the ecosystem. Page one mentions the MCP Registry. This looks like an N P M or a Maven Central but specifically for AI connectors. They have a C L I tool and even GitHub Actions integration. Herman, it feels like they are trying to build a marketplace.
It is a centralized publishing system. If you build a great server that connects to, say, the Brave Search A P I or a specific medical database, you can publish it to the registry. The GitHub Actions part is clever because it automates the C I C D of your server. This is how they solve the N times M problem. Instead of everyone building their own Google Drive connector, one person builds a high quality one, puts it in the registry, and everyone else just adds a few lines to their J S O N config to use it.
It is an ambitious project. The docs are nearly three hundred thousand characters across ten pages, which is a lot for a protocol that is still relatively new. My big takeaway is that if you are building anything in the agentic AI space, you cannot ignore this. It is clearly where the momentum is.
My one thing to remember is the distinction between tools and resources. If you are designing an MCP server, spend time thinking about what should be a tool and what should be a resource. Do not just make everything a tool. If the model just needs to read data, make it a resource. It is safer, faster, and follows the design philosophy of the protocol.
And for me, it is the absolute paths gotcha. Save yourself the headache. If you are editing that config file, go to your terminal, type P W D to get your present working directory, and copy that entire string. Do not guess.
Wise advice.
Well, that is our walk through of the Model Context Protocol documentation. Again, you can find the current version at model context protocol dot info slash docs. We recorded this on April third, twenty twenty six, so please go check the live docs for the latest updates. Things are moving fast in the world of AI agents.
Thanks for joining us.
We will see you next time on My Weird Prompts. Stay curious and keep building. Out.
Herman, I think we need to linger a bit more on that architecture because the docs really lean into this idea of the USB C for AI. It is not just a catchy slogan. On page two, they talk about the N times M integration problem. For the non engineers listening, that just means that if you have five AI models and five data sources, you normally have to write twenty-five different pieces of code to make them all talk to each other. MCP reduces that to five plus five. You write one connector for your data, and it works everywhere.
And the magic happens in that three-tier separation. You have the Host, which is the environment like Claude Desktop or VS Code. You have the Client, which is the part of the protocol that lives inside that host. And then you have the Server. The docs make a point that the Server is the authority on the data. It does not just hand over a raw database dump. It tells the client, here are the tools I have, here are the resources I can show you, and here is how you should ask me for things. It is a very polite, structured conversation.
Speaking of those conversations, let's dive into the vocabulary on page ten. We touched on it, but I want to get granular because this is where developers are going to spend their time. Tools, Resources, Prompts, and Sampling. These are the four pillars. Herman, if I am building a server for a weather A P I, walk me through how I would use these four things.
Great example. For a weather A P I, your Tools would be the active functions. You might have a tool called get current weather that takes a city name as an argument. When the AI wants to know the temperature in Seattle, it calls that tool. Now, Resources would be your static or reference data. Maybe you have a resource that is a list of all the weather station I D s or a documentation file on how to interpret storm warnings. The model can read that resource to get context before it decides which tool to call.
Okay, and then Prompts would be the templates?
Right. You might provide a Prompt called weather report summary. This template would tell the model, look at the current weather data, look at the forecast for the next three days, and write a professional memo for a travel agent. It saves the user from having to type all those instructions. You are basically shipping the best practices for your data right along with the data itself.
And Sampling is the one that still blows my mind. This is where the weather server could actually turn around and ask the AI a question?
Yes. Imagine the weather A P I returns a complex meteorological string of numbers and codes. The server could use the Sampling capability to say to the client, hey, I just got this weird data string, can you ask the model to translate this into plain English so I can process it further? It creates this back and forth where the server and the model are collaborating. The docs call this agentic workflow. It is less like a librarian handing you a book and more like a research assistant who reads the book with you and helps you highlight the important parts.
That is a huge shift from how we used to think about A P I calls. Usually, an A P I is a dead end. You send a request, you get a response, and that is it. With Sampling, the A P I call becomes a living process. But let's look at the implementation. Page eight has that five minute quickstart we mentioned. It focuses on the filesystem server. Herman, when people try this at home, they are going to see a lot of talk about N P X. Can you explain why the docs recommend that instead of just downloading a file?
N P X is a package runner for Node dot J S. The reason the MCP docs love it is because it ensures you are always running the latest version of the server code without cluttering up your machine with permanent installs. When you put that N P X command into your Claude config file, the host pulls the latest logic from the cloud every time it starts up. It keeps the ecosystem fresh. But, as you mentioned earlier, the big catch is the configuration file itself. One wrong comma in that J S O N file and the whole thing breaks.
I spent twenty minutes looking for a missing bracket in my Claude Desktop config. The docs mention a tool called the MCP Inspector on page six, and I wish I had used it sooner. It is a separate web interface where you can test your server in isolation. If you are building a server, do not just keep restarting your AI app to see if it works. Use the Inspector. It shows you the raw J S O N R P C messages flying back and forth. It is the closest thing we have to a DevTools for AI context.
And that brings us to the transport layer, which is another area where the docs get very specific. On page ten, they talk about S T D I O versus S S E. Most people are going to start with S T D I O, which stands for standard input and output. This is how your computer talks to itself. The AI host starts your server as a child process and they shout at each other through a private pipe. It is incredibly fast and incredibly secure because that pipe never touches the internet.
But it is also why MCP is currently a local first protocol. The docs are very transparent about the fact that remote hosts are still in active development. If you want to build a website that uses MCP to talk to your users' local files, you are going to hit a wall right now unless you build a custom bridge. They explain that this is a deliberate choice. They wanted to solve the local context problem first because that is where the most sensitive data lives. Your emails, your local code, your private notes. They do not want that data leaving your machine if it does not have to.
Now, if you are an enterprise developer, you might be thinking, I do not want to write Node dot J S or Python. I have a massive Java stack. This is where page six and seven of the docs really shine. The inclusion of a first class Java S D K and Spring AI integration is a massive signal. Usually, these AI protocols feel like they were built by and for people who only use Jupyter notebooks. But MCP has a full Spring Boot starter.
I was looking at the code snippets for the Java implementation. It is surprisingly clean. You use the at Tool annotation. You do not have to write a J S O N schema to describe your function to the AI. The S D K uses reflection to look at your Java method, sees the parameters and the return types, and automatically builds the documentation the model needs. It is basically self documenting code for AI.
It is the same philosophy as Swagger or Open A P I but for model context. And the docs highlight that this supports both synchronous and asynchronous workflows. If you have a database query that takes ten seconds, the Java S D K handles the waiting and the polling so the AI host does not just time out and give up.
Let's talk about the learning path on page three because I think it is the best part of the documentation. They call it Zero to Hero. They actually give you time estimates for each level. Level one is just understanding the concepts, which they say takes one to two hours. Level two is using existing servers, which is two to three hours. But level three, building your own, is where the meat is. Four to six hours. Herman, when you built your first one, what was the hardest part of that level three jump?
The hardest part is actually the prompt engineering within the server. It is one thing to get the code to run; it is another thing to describe your tool so clearly that the AI knows exactly when to use it. The docs have a whole section on writing effective tool descriptions. They tell you to avoid vague names like process data and instead use very specific names like calculate monthly revenue totals from C S V. You have to remember that the AI is your user, and the description is the only manual it gets.
That is a great point. The docs even suggest using an LLM to help you write the descriptions for your MCP tools. It is very meta. You ask the AI, hey, I wrote this function, how should I describe it to another AI so it uses it correctly?
It works surprisingly well. Now, the final piece of the puzzle in the docs is the MCP Registry on page one. This is the future of the protocol. Think of it like an app store for AI capabilities. If you need a connector for Slack, you do not build it. You search the registry, find the official one, and add it to your config. The docs mention a C L I tool for the registry and even GitHub Actions templates. They want you to be able to push a button and have your new data connector live for the whole world to use.
It feels like they are trying to build the plumbing for the entire agentic era. If this succeeds, we will stop talking about integrations and start talking about capabilities. You won't ask if an AI works with Jira; you will just ask if there is a Jira MCP server.
And ninety-nine percent of the time, the answer will be yes. But before we finish, Corn, we have to talk about the troubleshooting section on page nine. There are a few more gotchas. One is the environment variables. If your MCP server needs an A P I key, you cannot just set it in your terminal and expect Claude Desktop to see it. You have to explicitly define those keys inside the J S O N configuration file for the host.
That tripped me up too. I kept getting unauthorized errors even though my local environment was set up perfectly. The host app runs in its own little bubble, so you have to pass those keys through the bubble. The docs also mention that on Windows, you sometimes have to use double backslashes in your file paths because of how J S O N handles escape characters. It is the little things that will get you.
Always the little things. Another one is the log files. If your server is crashing, you won't see the error in the AI chat window. You have to go find the local log directory for the host app. The docs tell you exactly where those are for Mac, Windows, and Linux. If your hammer icon is missing, the logs are the first place you should look. They will tell you if there was a syntax error in your config or if the server failed to start.
Okay, let's wrap this up with some final takeaways. Herman, if someone is listening to this and they have five hours this weekend, what should they do with MCP?
Start with level two of the learning path. Download the filesystem server, get it running in Claude Desktop or an IDE, and just experience what it feels like to have an AI that can actually see your files. Once you see it organize a messy folder or summarize a local project, the lightbulb will go off. Then, move to level three and try to connect it to one of your own data sources. Even if it is just a simple text file or a small S Q L lite database. The power of being able to talk to your own data without uploading it to a third party is huge.
For me, the takeaway is the shift in architecture. We are moving away from monolithic AI apps and toward a modular ecosystem. MCP is the glue. It is not the flashiest part of the AI world, but it might be the most important part for actual productivity.
Agreed. It is the boring plumbing that makes the fancy stuff possible.
Well, that is episode one thousand eight hundred and eighty. We have walked through the Model Context Protocol docs from the architecture to the Java S D K to the troubleshooting gotchas. As a reminder, we were looking at the docs at model context protocol dot info slash docs, scraped on April third, twenty twenty-six.
Check the live site because by the time you hear this, they might have released the remote host support or new transport layers. This protocol is evolving at breakneck speed.
Thanks for the deep dive, Herman. And to our listeners, thanks for sticking with us through the technical weeds. We hope this makes your next AI project a little bit smoother.
Keep building, everyone.
We will be back next week with another Talk Through The Docs. Until then, stay curious and keep your J S O N brackets closed. This is My Weird Prompts, signing off. Out.
