Wiring Up MCP: a Hand-Written JSON-RPC Client, Two Transports, and a Tool Namespace

The protocol's three concerns, and the sliver we use today

Scope first. An MCP server offers tools, resources and prompts, and today we wire up only tools — tools are what the model reaches for on its own, while the other two are closer to "a human picks something and pastes it into the context."

Then the version. This course is written against the 2026-07-28 specification, which differs from many tutorials online by enough to send you down the wrong road. Three differences matter most.

One: the protocol is stateless. No initialize handshake, no handshake-complete notification. Version, identity and capabilities live in the _meta field of every request, repeated each time. It sounds wordy; the payoff is that any request can land on any replica without sticky routing.

Two: the server no longer sends JSON-RPC requests to the client. It puts "here is what I still need" into the result, and the client fills the gap and resends under a new id. We do not implement that branch today, but you must recognize it — a client that cannot will hand the model an unfinished result as if the work were done.

Three: two transports remain, stdio and Streamable HTTP. The previous version's separate long-lived GET, session header and stream resumption are gone — not deprecated, removed.

A complete request looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": { "query": "division by zero" },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": { "name": "mca", "version": "0.15.0" }
    }
  }
}

Each key has a job. The version is mandatory; a server that rejects it answers -32022 with the versions it supports. Capabilities are mandatory too, and since this client neither renders forms nor lends the model out, it declares an empty object. The client identity is optional self-description, and the specification notes that nothing verifies it, so it may be displayed and logged, and must never inform a security decision.

One more trap: _meta hangs on params, not on the top level of the message. Get it wrong and the server says you failed to declare capabilities, when you clearly did — somewhere it does not look.

Hand-writing JSON-RPC: numbering, correlation, timeouts, teardown

The code at this layer is short, because it does four things.

Numbering: one incrementing id per request, unique only within this connection. Correlation: an incoming message finds the Promise waiting on its id, and a message with no id is a notification, not a response. Timeouts: over stdio, a server that never answers never answers, and that await hangs forever with the whole Agent behind it; there is no standard value to pick, but having none is always wrong. Teardown: when the transport dies, fail every waiting request at once, or a server that failed to start makes each request wait out its own timeout.

request(method: string, params: Record<string, JsonValue> = {}) {
  if (this.dead) return Promise.reject(this.dead)
  const id = this.nextId++
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      this.pending.delete(id)
      reject(new McpError(`${method} timed out`))
    }, this.timeoutMs)
    this.pending.set(id, { resolve, reject, timer })
    this.transport.send({ jsonrpc: '2.0', id, method, params: withMeta(params) })
  })
}
 
private onMessage(message: JsonRpcMessage): void {
  // No id means a notification, not a response. Clients that correlate by
  // arrival order or array index go off by one right here
  if (typeof message.id !== 'number') return
  const waiter = this.pending.get(message.id)
  if (!waiter) return // A late response: it already timed out. Drop it, do not raise
  this.pending.delete(message.id)
  clearTimeout(waiter.timer)
  if (message.error) reject_(waiter, message.error)
  else waiter.resolve(message.result ?? {})
}

async def request(self, method: str, params: dict | None = None) -> dict:
    if self.dead:
        raise self.dead
    self.next_id += 1
    request_id = self.next_id
    future: asyncio.Future = asyncio.get_running_loop().create_future()
    self.pending[request_id] = future
    await self.transport.send(
        {"jsonrpc": "2.0", "id": request_id, "method": method, "params": with_meta(params or {})}
    )
    try:
        # Let asyncio own the timeout, which also clears the future on cancel
        return await asyncio.wait_for(future, self.timeout_s)
    finally:
        self.pending.pop(request_id, None)
 
 
def on_message(self, message: dict) -> None:
    request_id = message.get("id")
    if not isinstance(request_id, int):  # No id means a notification, not a response
        return
    future = self.pending.get(request_id)
    if future is None or future.done():  # A late response: drop it, do not raise
        return
    if "error" in message:
        future.set_exception(McpError(message["error"].get("message", "")))
    else:
        future.set_result(message.get("result", {}))

Fetching the tool list has one more unavoidable trap: tools/list is paginated. The server on your machine finishes in one page; the one your user installed may take ten. There is exactly one stopping rule — the absence of a next-page cursor. Do not guess from "this page is shorter than the last" (the specification never promises full pages), and do not parse the cursor (it is opaque, so pass it straight back). The failure is quiet: the user simply sees fewer tools, and nothing reports an error. The demo notes server holds three tools and returns two per page precisely to catch this.

stdio: one never-ending stream, and you draw the boundaries

The difference between the two transports is not speed; it is who draws the boundary of a message. On stdio the bytes are one never-ending stream and you split on newlines yourself, which produces today's most commonly miswritten line. The instinctive version:

child.stdout.on('data', chunk => {
  for (const line of chunk.split('\n')) handle(line)   // this line is wrong
})

What is wrong: one data event is not one line. It is "whatever was left over, plus some whole lines, plus a new leftover." The operating system guarantees byte order, not boundaries. Small messages behave perfectly; a tool result of a few kilobytes is certain to be cut in half, and parsing starts failing — unstably, too: fine on your machine, broken on the next one. The fix is a buffer that only hands out the part that ended in a newline:

export class LineFramer {
  private buffer = ''
 
  /** Feed a chunk of bytes, get back every complete line inside it */
  push(chunk: string): string[] {
    this.buffer += chunk
    const parts = this.buffer.split('\n')
    // The last piece has no trailing newline: it is half a line, keep it for next time
    this.buffer = parts.pop() ?? ''
    return parts.map((line) => line.trim()).filter((line) => line.length > 0)
  }
 
  /** At end of stream, hand back the leftover, or the final message is lost */
  flush(): string[] {
    const rest = this.buffer.trim()
    this.buffer = ''
    return rest ? [rest] : []
  }
}

class LineFramer:
    """Frame on newlines. Half a line stays in the buffer until the next chunk arrives."""
 
    def __init__(self) -> None:
        self._buffer = ""
 
    def push(self, chunk: str) -> list[str]:
        self._buffer += chunk
        # The last piece of str.split is exactly that half line, so keep it
        *complete, self._buffer = self._buffer.split("\n")
        return [line.strip() for line in complete if line.strip()]
 
    def flush(self) -> list[str]:
        rest, self._buffer = self._buffer.strip(), ""
        return [rest] if rest else []

Everything else stdio asks of you is about process lifecycle. Three rules.

Server logs go to stderr, and only stderr. One stray character on standard output and the client's parser starts complaining, in language that sounds like a broken protocol and mentions nothing about logs. Our matching guardrail: an unparseable line is recorded once and does not kill the transport.

A child process does not die with its parent. Kill it explicitly on exit, closing standard input first. Skip this and a few runs later the machine carries a trail of orphans.

A failure to start must surface immediately. A mistyped command or a missing dependency arrives on the process error event rather than the exit event, so catch both and translate either into "every waiting request fails together."

Streamable HTTP: one POST, two response shapes

On the HTTP side, HTTP draws the boundaries for you, so there is no framing to write. The cost shows up elsewhere.

First, the mandatory headers. This version adds three to every POST, mirroring the body's key fields onto the envelope:

POST /mcp HTTP/1.1
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search

Why duplicate them? Because middleboxes should not have to parse a body in order to route. A gateway splitting traffic by method name, or rate-limiting call requests specifically, needs only the headers. And once the middlebox decides on headers while the server executes on the body, a mismatch between the two is a vulnerability: a gateway configured for "listing is free, calling needs auth" is walked straight past by a request whose header says list and whose body says call. So the specification requires the server to verify that headers and body agree, answering 400 with -32020 when they do not. The demo server implements that check, and the self-test really sends a mismatched request at it.

An encoding note: HTTP header values are limited to visible ASCII, so a non-ASCII tool name cannot be expressed directly. The specification defines a sentinel format wrapping the Base64 of the raw bytes, and the server must decode before comparing.

Second, the response comes in two shapes, chosen by the server on the spot. A simple request gets ordinary JSON; a possibly slow one gets an event stream with progress notifications in the middle and the response, carrying the id, at the end. The client must accept both, and must not assume the last message in the stream is the response — the server is free to send a log notification after the result. One criterion: the message whose id matches is the response. Paired with it: a stream ending is not a request succeeding, so a mid-stream break must raise, or the caller waits out the timeout and the real cause is gone.

The demo ticket system answers exactly this way: a call emits a progress notification and then the result, and the self-test asserts "one notification plus one response correlated by id" — a client that mistakes the notification for the response reads "looking up the ticket system" and believes it is finished.

Which transport when: local things that travel with your machine use stdio; cross-machine things shared by a team use HTTP. The failure modes are symmetric — stdio fails by a process that will not start, logs polluting standard output, and orphaned children; HTTP by connection refused, a broken stream, and a middlebox rewriting things.

Aggregation and namespaces: what to do with two tools called search

Now mount both servers at once: a notes library over stdio, a ticket system over HTTP. Each ships a tool called search — not a coincidence but an inevitability, since the specification only guarantees a tool name is unique within a single server. Disambiguation is the client's job, under one hard constraint: a server's self-reported name is not guaranteed unique across servers, so it must not be the basis for disambiguating. The prefix has to come from an alias in our own configuration, and a duplicate alias is a configuration error that should explode at startup rather than wait for the model to call the wrong tool. The shape is then bounded by what model APIs accept — most allow letters, digits, underscores and hyphens up to 64 characters — so we settle on mcp__alias__toolname.

export function namespacedName(alias: string, toolName: string): string {
  const raw = `mcp__${alias}__${toolName}`.replace(/[^A-Za-z0-9_-]/g, '_')
  if (raw.length <= 64) return raw
  // Truncation manufactures fresh collisions; the hash puts uniqueness back
  const digest = createHash('sha1').update(`${alias}::${toolName}`).digest('hex').slice(0, 6)
  return `${raw.slice(0, 57)}_${digest}`
}
 
// Reverse lookup goes through this table only. Never split the string back into
// alias and original name: tool names are allowed to contain underscores, and a
// truncated, hashed name cannot be taken apart at all
entryOf(localName: string) {
  return this.entries.get(localName)
}

def namespaced_name(alias: str, tool_name: str) -> str:
    raw = re.sub(r"[^A-Za-z0-9_-]", "_", f"mcp__{alias}__{tool_name}")
    if len(raw) <= 64:
        return raw
    # Truncation manufactures fresh collisions; the hash puts uniqueness back
    digest = hashlib.sha1(f"{alias}::{tool_name}".encode()).hexdigest()[:6]
    return f"{raw[:57]}_{digest}"
 
 
# Reverse lookup goes through this dict only, never through split("__")
def entry_of(self, local_name: str) -> Entry | None:
    return self.entries.get(local_name)

Next comes the step most often written wrong: what goes back to the server on a call is the original name. The prefixed name circulates only between the model and the client; the server has never heard of it, and the symptom is that every remote call answers "no such tool." One technique goes with it: write the source into the description, because the description is the model's only basis for choosing a tool.

Everything else at this layer should be spent on failure, under one rule: try and catch each server during discovery, and never throw during a call. At discovery, wrap each server separately, record the reason and move to the next. At call time, translate every failure into a failed tool result, because the model can only change course if it can see what happened. This lab points the ticket system at an empty port and leaves the notes library's three tools usable — when one server dies, the worst outcome should be a few missing tools, not a failed turn.

One last thing: a dropped connection must be visible to the user. Quietly removing the dead server from the list makes the model behave as if that capability never existed, saying only "I could not find a related ticket." Losing a hand is an incident; pretending the hand was never there is a bigger one.

The trust boundary: who issues whose permit

Today's last decision is the only one that touches security directly.

A remote tool definition may carry annotations, one of which says "this is read-only." It looks exactly right: let read-only calls through, ask the user about the rest. But it cannot be believed, for one reason: it is a permit the callee issued to itself. The specification says so bluntly — a client must treat tool annotations as untrusted input.

So this course fixes one rule: remote tools are all treated as if they change things, landing in the ask branch of day five's approval gate. Permission tri-state and rule matching were covered on day five and are not repeated here — today's job is simply not to route around it.

Just as free is day three's truncation: remote and local results share the same 8000-character budget. This lab reads a deliberately long note and the result is truncated to 8052 characters — the 8000 of body plus a sentence saying how much was cut — on exactly the local path.

All of this works because to the loop, a remote tool is just one more tool definition. Not one line of the kernel changes today: truncation, approval, loop detection and snapshots all take effect automatically. This is another dividend from day two's layering — as long as a new capability can be expressed as a tool, it inherits every mechanism of the previous fourteen days for free.

One boundary: mounting must happen before the session is created, because the tool list is built once. Doing it mid-run is possible, and the price is that adding or removing tools dynamically invalidates the prompt cache (the tool table sits in the prompt prefix). That is a different decision, and this course does not make it.

Source Reading

Hands-On Lab

The two demo servers in the lab directory are not exercises, they are what you connect to: the notes library runs as a child process with three tools returned two per page, and the ticket system runs on port 3115 and collides with it on search. Today leaves five exercises, all traps where the instinctive version behaves perfectly on small data: framing by splitting on newlines, taking only the first page, treating the stream's last message as the response, believing the self-declared read-only flag, and sending the namespaced name back to the server. The starter passes four of fourteen unmodified.

1. Give the framer its buffer, then watch the first item and the long-note assertion turn green — the latter failed because a multi-kilobyte result was cut in half.
2. Turn tool listing into a pagination loop with "no next cursor" as the criterion, and watch the notes library go from two tools to three.
3. Make the event-stream branch hand up every message and use the id to pick the response, then watch the notification count go from 0 to 1.
4. Force every remote tool's read-only flag to false, and watch the self-declared read-only search tool wait for approval too.
5. Send the original name back to the server, run MOCK=1 SELFTEST=1 pnpm start for 14 of 14, then use the README's pipe commands to inspect the namespace, the approvals and the failure isolation.

Acceptance is five ticks: the self-test passes all 14 items; pagination surfaces three tools; one remote call receives one notification plus one response correlated by id; the two search tools coexist and each reverses back to its original name; and pointing the ticket system at an empty port leaves the notes library working, with a call to it producing a failed result rather than an exception.

Interview Questions

Today's three questions test implementation judgment for a protocol client, not "what is MCP":

1. Hand-writing an MCP client without an SDK, which protocol details must you handle?
2. Where do stdio and Streamable HTTP each fit? How do their failure modes differ?
3. Aggregating third-party tools into your own Agent, what governance would you add?

Full prompts, analyses and key points are in this course's day-fifteen question bank. Question three discriminates most — most answer "prefix them to avoid collisions," and few can say why a server's read-only declaration must not be used as a permission.

Checklist and Tomorrow

• I can say where version and capabilities live under a stateless protocol, and what a misplaced _meta looks like
• I can name a JSON-RPC client's four jobs: numbering, correlating by id, timing out, and tearing down at once
• I can explain why "no id means a notification" cannot be skipped
• I can state the one criterion for pagination, and why getting it wrong reports no error
• I can explain where half a message comes from, and why it only shows up on large results
• I can name stdio's three lifecycle rules: logs to stderr, explicit teardown, failures surfacing immediately
• I can say why the three mandatory headers exist, and why a header-body mismatch is a vulnerability
• I can say why the last message in an event stream is not necessarily the response
• I can explain why the prefix must come from our own alias, and why reverse lookup goes through a table
• I can say why a self-declared read-only flag must not decide whether to ask for approval

Tomorrow is D16, "Loading Skills: Scanning, Progressive Disclosure, and Trigger Judgment." Today we wired up someone else's tools; tomorrow, someone else's experience. The difference is worth thinking about in advance: a tool occupies a slot in the tool list, while experience is just text — so on what grounds does it also need loading on demand?