In the first part I followed one question from your prompt to an MCP server and back, and every payload on the way was printed for you. At the end I promised to send such messages myself. So this time thereâs no host and no model, only a server in a terminal and me typing JSON.
I also wrote that you donât write the _meta block by hand. Well, today I do.
A server without a host
The filesystem server was the first entry in the config last time. A host would start it for me. Now I do that myself, in a new folder with one file in it:
demo_dir=$(mktemp -d "${TMPDIR:-/tmp}/mcp-demo.XXXXXX") && cd -P "$demo_dir" && printf 'replicas: 3\nimage: ghcr.io/example/api:1.4.0\n' > deployment.yaml && npx -y @modelcontextprotocol/server-filesystem@2.3.0 .Secure MCP Filesystem Server running on stdioEffective allowed directories (from the command line): /tmp/mcp-demo.A1B2C3I shortened the directory name here and in the replies below. Yours will differ, and on macOS itâs a long path under /private/var/folders. After that nothing happens. Thereâs no prompt. The server just waits.
This is already the whole stdio transport. The server reads messages from standard input and writes its answers to standard output, and every message is one line of JSON. The three lines above went to standard error, which is where a stdio server is allowed to log.
A message canât contain a literal line break, so I write every request on one line. I paste each one into the terminal where the server is waiting and press Enter. The . at the end of the command makes the current directory the only allowed directory in this run. Iâll come back to that.
Who are you
The first line I paste is a server/discover request:
{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"0.1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}Most of that line is the _meta block. Every request in this version needs io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities. The spec also recommends io.modelcontextprotocol/clientInfo, so I give myself a name.
The answer comes back as one line too. Indented it looks like this:
{ "result": { "supportedVersions": ["2026-07-28"], "capabilities": { "tools": { "listChanged": true }, "resources": { "listChanged": true } }, "resultType": "complete", "ttlMs": 0, "cacheScope": "private", "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "secure-filesystem-server", "version": "2.3.0" } } }, "jsonrpc": "2.0", "id": 1}The server speaks 2026-07-28 and has tools and resources. It doesnât offer prompts. listChanged means it can notify clients that subscribe when one of those lists changes. ttlMs: 0 makes the answer stale right away, and cacheScope: "private" tells clients to keep separate caches for different credentials. The server gives its name and version in _meta, as the spec recommends for each result.
A client doesnât have to call discovery, but every server that speaks 2026-07-28 has to answer it. A server that only knows the 2025 versions doesnât have this request and expects initialize. On stdio the spec recommends starting there when a client supports both the old and new protocols. This server uses the first request to pick which one to speak. When my first line was a tools/list without _meta, the server took me for a 2025 client. It stayed with the old format even when I sent _meta on later lines. Thatâs how this server treats old clients on stdio. The spec itself wants every request with _meta handled on its own.
What a tool looks like
Next I ask the server what tools it has.
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"0.1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}The answer is a single line of 19,571 characters with 16 tools in it, so it fills the terminal. I look for read_text_file, the second tool, near the start. Its description says to use it to examine one file, and its inputSchema says it needs a string named path. Thatâs enough to read my file. This is the whole definition:
{ "name": "read_text_file", "title": "Read Text File", "description": "Read the complete contents of a file from the file system as text. Handles various text encodings and provides detailed error messages if the file cannot be read. Use this tool when you need to examine the contents of a single file. Use the 'head' parameter to read only the first N lines of a file, or the 'tail' parameter to read only the last N lines of a file. Operates on the file as text regardless of extension. Only works within allowed directories.", "inputSchema": { "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "properties": { "path": { "type": "string", "description": "The file to read as text. Absolute, or relative to an allowed directory; it must resolve inside the allowed directories." }, "tail": { "description": "If provided, returns only the last N lines of the file", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "head": { "description": "If provided, returns only the first N lines of the file", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["path"] }, "annotations": { "readOnlyHint": true, "idempotentHint": true, "destructiveHint": false, "openWorldHint": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string" } }, "required": ["content"], "additionalProperties": false }}name is what I put in tools/call. It only needs to be unique on this server, so a host can add a server prefix when it sends tool names to a model. A host can show the title to people and pass the description and the argument schema to the model. The description of list_directory even points the model to two other tools. Thatâs handy, but itâs also a server writing instructions for the model that I normally never see. The first tool, read_file, uses its title and description to say itâs deprecated. Iâll get to the annotations after I try a write.
The list has the same ttlMs: 0 and cacheScope: "private" as the discovery answer. Close to half of the line is text from tool and argument descriptions. That text takes up context when a host sends it to the model. Some hosts load full descriptions only when they need them, as we saw in the first part.
Calling one
Now the request a client sends after the model asked for a tool. I play the model as well and pick the arguments:
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"read_text_file","arguments":{"path":"deployment.yaml"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"0.1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}{ "result": { "content": [ { "type": "text", "text": "replicas: 3\nimage: ghcr.io/example/api:1.4.0\n" } ], "structuredContent": { "content": "replicas: 3\nimage: ghcr.io/example/api:1.4.0\n" }, "resultType": "complete", "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "secure-filesystem-server", "version": "2.3.0" } } }, "jsonrpc": "2.0", "id": 4}I gave it a relative path and the server resolved it against its allowed directory, like the schema said it would. The IDs are arbitrary, the server copies mine into the reply. They jump around because I sent more requests than I show here.
The file is in there twice. content is a list of blocks that a host can pass to the model. A block can contain text, an image, audio, a link to a resource or an embedded resource.
This server puts the raw YAML in the text block. It also puts the YAML in a JSON object with one string field named content, as its outputSchema describes. Code can read that field directly. For clients that donât support structuredContent, the spec recommends that servers also put the serialized JSON in a text block. This server puts the plain YAML there instead.
resultType says the call is finished. The other value in the core protocol is input_required, which is how the elicitation from the first part starts.
Two kinds of errors
The issues server from the first part doesnât exist here. I call its tool anyway:
{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"issues_search","arguments":{"query":"is:open label:bug"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"0.1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}{ "jsonrpc": "2.0", "id": 9, "error": { "code": -32602, "message": "Tool issues_search not found" }}Thatâs a protocol error. JSON-RPC puts the error in error, and -32602 means invalid parameters.
Now a tool that exists, with a path it isnât allowed to read:
{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"read_text_file","arguments":{"path":"/etc/hosts"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"0.1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}{ "result": { "content": [ { "type": "text", "text": "Access denied - path outside allowed directories: /etc/hosts not in /tmp/mcp-demo.A1B2C3" } ], "isError": true, "resultType": "complete" }, "jsonrpc": "2.0", "id": 10}This one is a tool execution error. The server understood the request and the tool refused it, so the reply has a result marked with isError: true. The last path in the error will be your demo directory.
The host should pass a tool execution error to the model so it can read the text and try something else. A protocol error means the server never got as far as running a tool. Here thatâs because no tool has that name.
I can also give a tool an input that fails its schema. This request has the right shape for tools/call, but the tool expects a string for path.
{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"read_text_file","arguments":{"path":42},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"0.1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}I get isError: true again, with this text.
Input validation error: Invalid arguments for tool read_text_file: path: Invalid input: expected string, received numberThat makes sense to me. The model wrote the arguments, so the model should hear what was wrong with them.
Two more mistakes are mine and not the modelâs. The first is a request without the _meta block:
{"jsonrpc":"2.0","id":16,"method":"tools/list","params":{}}{ "jsonrpc": "2.0", "id": 16, "error": { "code": -32602, "message": "Request is missing the required _meta envelope for protocol revision 2026-07-28 (io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientCapabilities)" }}As my first line a request like that made the server switch to the 2025 protocol. After discovery itâs an error.
The second is a line that isnât complete JSON. I lose a bracket while pasting and press Enter. JSON-RPC has a parse error for that, -32700, but this server prints nothing. It just keeps waiting for the next line.
Nobody asked me
So far I only read. This call writes:
{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"write_file","arguments":{"path":"notes.txt","content":"written over stdin\n"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"0.1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}The text in the result is Successfully wrote to notes.txt. I press Ctrl-D on a blank line to close standard input and get my shell prompt back. The file is there.
cat notes.txtwritten over stdinThe server didnât ask if Iâm sure. It sees the same request whether a host asked me first or I typed it in my terminal. A server can ask for confirmation through elicitation if the client supports it, but thatâs the serverâs choice. This tool just writes the file.
The approval prompt you know from your coding agent belongs to the host. The spec recommends that the application give a person a way to deny tool calls.
On this connection the server does enforce the directory limit. It refused /etc/hosts because that file is outside the demo directory, and it would refuse a host the same way. Its README names two limits of that check. A 2025 client that supports roots can replace the allowed directories unless I start the server with --confine-roots. And the check goes by path, so a hard link inside the directory can still lead to a file outside.
Hints and limits
The server wonât ask, but it does describe its tools, in the annotations. These are the ones of write_file:
{ "readOnlyHint": false, "idempotentHint": true, "destructiveHint": true, "openWorldHint": false}| Hint | When itâs true | Default |
|---|---|---|
readOnlyHint | The tool doesnât change anything | false |
destructiveHint | It may overwrite or delete data | true |
idempotentHint | Calling it again with the same arguments changes nothing more | false |
openWorldHint | It may interact with an open set of external systems, like a web search tool does | true |
The defaults assume the tool could make destructive changes or interact with external systems. The destructive and idempotent hints apply to tools that can make changes.
A host can use them, for example to ask before write_file and not before read_text_file. But every one of these names ends in âHintâ, and they are what a server says about itself. The spec tells clients not to base decisions on annotations from a server they donât trust.
A limit looks different. From the same demo directory, I start the server again with one more option.
npx -y @modelcontextprotocol/server-filesystem@2.3.0 --read-only .I paste the discovery request again, then paste the same tools/list line. It now returns 10 tools instead of 16. They all have readOnlyHint: true, and the reply is about 12,400 characters.
I try write_file again, with a new file name.
{"jsonrpc":"2.0","id":24,"method":"tools/call","params":{"name":"write_file","arguments":{"path":"notes2.txt","content":"should not exist\n"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"0.1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}{ "jsonrpc": "2.0", "id": 24, "error": { "code": -32602, "message": "Tool write_file not found" }}In read-only mode the server removes every tool it didnât mark readOnlyHint: true, so I get the same answer as for the tool that never existed. The hint and the limit come from the same annotation here. The difference is who acts on it, and this time itâs a server I started myself. The process can still write as my user, so for a hard limit Iâd add file permissions. Thatâs the kind of switch I meant when I wrote to start with read-only servers.
I press Ctrl-D again and remove the demo directory.
cd ~ && rm -r "$demo_dir"The same over HTTP
A server can get the same requests as HTTP POSTs. The filesystem server uses stdio, so here I use the everything server. Itâs a test server from the same repository with a bit of every MCP feature in it. I start it in one terminal and leave it running.
npx -y @modelcontextprotocol/server-everything@2.3.0 streamableHttpStarting Streamable HTTP server...MCP Streamable HTTP Server listening on 127.0.0.1:3001npm may print a deprecation warning before those two lines. In a second terminal I call its echo tool with curl.
curl -sS -i http://127.0.0.1:3001/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2026-07-28' \ -H 'Mcp-Method: tools/call' \ -H 'Mcp-Name: echo' \ -d '{"jsonrpc":"2.0","id":31,"method":"tools/call","params":{"name":"echo","arguments":{"message":"hello"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"0.1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'HTTP/1.1 200 OKcontent-type: application/json
{"result":{"content":[{"type":"text","text":"Echo: hello"}],"resultType":"complete"},"jsonrpc":"2.0","id":31}The real reply is much longer, because this server puts two icons into _meta. The body is the kind of line I pasted into the terminal before. Three headers copy values from that line. MCP-Protocol-Version carries the version from _meta, Mcp-Method carries the method, and Mcp-Name carries the tool name. A load balancer or a gateway can use those headers to route or limit requests without parsing JSON.
A copy can be wrong, so the server compares. I run the curl command again with "id":34 and the Mcp-Name header changed to get-sum. The body still says echo. I get 400 Bad Request and this error.
{ "jsonrpc": "2.0", "error": { "code": -32020, "message": "Bad Request: the request headers and body disagree: the body carries params.name=\"echo\" but the Mcp-Name header names \"get-sum\"" }, "id": 34}Without that check a proxy in front could decide on the header while the server runs whatâs in the body.
I run it one more time with issues_search in both the header and the bodyâs tool name. I get the same -32602 error as on stdio, with a 200 OK in front of it. I have to read the body to see what happened.
The Accept header names two formats because the server picks one per request. The echo reply was a single JSON object. The everything server also has a tool that takes a while, trigger-long-running-operation. I give it two seconds and two steps, and ask for progress with a progressToken in _meta. I add -N so curl prints the events as they arrive.
curl -sS -i -N http://127.0.0.1:3001/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2026-07-28' \ -H 'Mcp-Method: tools/call' \ -H 'Mcp-Name: trigger-long-running-operation' \ -d '{"jsonrpc":"2.0","id":40,"method":"tools/call","params":{"name":"trigger-long-running-operation","arguments":{"duration":2,"steps":2},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"0.1.0"},"io.modelcontextprotocol/clientCapabilities":{},"progressToken":"p1"}}}'HTTP/1.1 200 OKcontent-type: text/event-stream
event: messagedata: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progress":1,"total":2,"progressToken":"p1"}}
event: messagedata: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progress":2,"total":2,"progressToken":"p1"}}
event: messagedata: {"result":{"content":[{"type":"text","text":"Long running operation completed. Duration: 2 seconds, Steps: 2."}],"resultType":"complete"},"jsonrpc":"2.0","id":40}Thatâs the âstreamableâ in Streamable HTTP. Two notifications come first. They have no id because nobody answers them. Then I get the result, and the stream ends.
This demo server listens on the loopback address and accepts these calls without credentials. That keeps other machines out, not other programs on mine. The spec requires HTTP servers to check the Origin header, so a website in my browser canât call them, and it recommends authentication. This server checks the origin. It also has a tool that returns its environment variables, so I donât leave it running. How a protected server checks a token is a topic for a later part. I stop the server with Ctrl-C in its terminal.
Whatâs next
I left out a few things about tools. Long lists can come in pages. Servers can notify clients when the list changes. HTTP can also carry selected tool arguments in headers.
You donât have to type all of this either. The MCP Inspector sends the same requests from a web UI, a command line or a terminal UI. Iâd still do it by hand once. After that a tool call isnât magic anymore. Itâs one line of JSON going in and one coming back.
The discovery answer said this server has resources too. Next time Iâll try to read the same deployment.yaml with resources/read and see what a host can do with the result.