Video: JSON message types
1. Video: JSON message types
We have gotten through a couple of topics, and before we move on, I just want to give you a little heads up. You see, the next two or three videos are going to be focused on MCP messages and the standard IO transport. These videos might seem a little bit dry and a little bit boring, but there's a very important reason that we're going to cover these topics. One of the big goals of this course is to help you understand the streamable HTTP transport, which allows clients to connect to remotely hosted MCP servers. The issue is that in some cases, there are some big limitations on what a MCP server can do when it is using the HTTP transport. Understanding those limitations can be rather challenging, and it's a lot easier to understand if you have a solid footing in MCP messages and a standard IOTransport. So that's why we're going to spend some time on these first two topics. So with all this in mind, let's take a look at the format that MCP uses to communicate, specifically the messages format. Clients and servers communicate using JSON. We refer to these snippets of JSON as messages. There are many different types of messages defined inside the MCP spec, each of which are designed for a distinct purpose. So let me show you an example right away. As an example, if a language model connected to a MCP client decides to call a tool provided by MCP server, the client will send a message over to the server. This type of message is named a call tool request, and I've got an example of a call tool request at the top of this diagram. The MCP server will then run the tool, and then put the result of the tool run into another message type named a call tool result, and I've got an example of that on the bottom of the diagram as well. Now, as I mentioned, the MCP spec defines a full list of all the different message types. You can find the full list inside the mcpspec repository hosted on GitHub, and we're going to take a look at that in just a moment. But first, to be clear about this repository that we're going to take a look at, this specification repo is separate from all the different SDK repositories, like the Python or the TypeScript mcpsdks. This specification repo has some different documents that describe how the mcpspec works. So in this repository, the full list of message types is written inside of a TypeScript file. Again, to be clear here, this TypeScript file isn't ever executed by anything, it's not included in any of the different SDKs. The types are just written in TypeScript, because TypeScript is a really convenient language for describing type data. So I'd like to show you this schema file that lists out all the different message types, just because there are some really interesting insights to be pulled out of it. So I'm going to navigate to the address you see up here at the top the screen and then inside this repository you will find at a certain path a file called schema.ts. The schema.ts file contains all the different message types that are available to us. So inside this file I can do a search for call tool request and here we go here's an example of what a call tool request looks like. So a call tool request must have a method of tool slash call and then a params object that has the name of the tool we want to call and some arguments to pass into it. You might notice that in the diagram I showed you a moment ago, back over here, there's also this JSON RPC and an ID on there as well. Those are actually defined on a separate object back inside the schema file called a JSON RPC request. So if I look that up, I'll see, okay, here is JSON RPC request, and it also must have an ID as well. Now out of this entire file, what I really want you to focus on are some different types that are defined at the very bottom. So I'm going to scroll down to the very bottom, very, very bottom of the file. I'll then scroll up just a little bit and I'm going to find a comment that says Server Messages and a comment that says Client Messages. You'll notice that inside these two sections, there are some kind of similarly named types. So inside of Client Messages, there are Client Request, Client Notification, and Client Result. And then down inside the Server section, there is Server Request, Server Notification, and Server Result. So let me show you a diagram that can help you understand what these different types inside this file, and specifically the client and server sections are really telling us. Okay, here we go. So inside that type file, we can kind of divide all these different types of messages into two or three different categories. First, on the left hand side of this diagram, there are request result messages. These are message types that always come in pairs. They're always going to have a name of something, something request, and then a paired message type of something, something result. So as an example, we have call tool request that gets paired up with a call tool result. We have a initialized request that gets paired up with a initialized result. All these different message types, I bet you could guess what they do for us. They describe messages that we send off either to a client or a server, and then the type of message that we expect to get back in response. So if I ever send off a call to request, I would expect to get back a call tool result. The other type of messages that we're we're going to work with are notification messages. These are more like events. They tell the client or the server about something that just occurred, but they don't really need a response. So we have types like progress notification, logging message notification, tool list change notification, and so on. Now back inside of the type file that we're looking at a moment ago, you may have noticed that we have the headers here of server messages and client messages. These comments and the types inside of each one are meant to indicate whether or not these types of messages are meant to be sent by the client or the server. So for example, this client request type describes all of the different types of requests that are expected to be sent from the client. And likewise down here, these are all requests that are expected to be sent from the server. And the same thing for server notifications. These are all notifications issued by the server. And these are all notifications that are issued by the client. So we can kind of summarize everything in a diagram a little bit like this. Now this doesn't show every type of message, I just mean to indicate that there are some requests that are meant to come from the MCP client, and I've got examples of those right here. There are results that are meant to come from the server. There are results that are meant to be sent from the client, there are requests that are meant to be sent from the server, and so on. Alright, so here's the critical thing that I want you to understand. The big takeaway from this video that's going to become really important as we start to talk about the streamable HTTP transport. The big critical thing to understand here is that there are a bunch of different messages that are meant to be sent from the server over to the client. So the server request types right here and the server notification types. These are all messages that are gonna be sent from the server over to the client. And I know right now that might seem like just completely irrelevant, just why is that important to know at all? Again, this is going to become really important as we start to look at the streamable HTTP transport. So just keep that in mind for a little bit.2. Let's practice!
Create Your Free Account
or
By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.