Writing Your First MCP Server: stdio Transport, the Official SDK, Parameter Schemas, Tool Annotations, and Debugging With Inspector

Today's Goals

1. Stand up a stdio server with the official SDK, and see its registered tools appear in a client
2. Write a usable input schema, output schema, and description for a tool, and explain who the description is written for
3. Distinguish protocol errors from tool execution errors, and give an example of when to use each

Yesterday you took a tools/call message apart field by field. Today, the reverse: write a process that genuinely emits messages like that. There is not much code, and the hard part is a few decisions — how detailed the description gets, how the schema is divided, which class an error falls into. Come back and tick off the three goals above.

Plain-Language Walkthrough

The stdio transport: one message per line, and one extra character breaks everything

Yesterday said the protocol is the plug standard. The transport, then, is the cable, and stdio is a cable run across the room: the client launches the server as a child process, and the two talk directly over standard input and standard output. No port, no domain, no authentication, because they were already on the same machine under the same user.

The rules are few enough to state in one breath. Messages are JSON-RPC, one per line, newline-delimited, with no bare newline inside a message. The client writes requests to the server's standard input and the server writes responses back to standard output. A server must not write anything to standard output that is not an MCP message; a client must not write JSON-RPC responses to the server's standard input (a client only sends requests and notifications). For logging, use standard error — the spec explicitly permits a server to write arbitrary UTF-8 text to standard error and reminds clients not to treat output on standard error as a signal of failure.

Shutdown is simple too: the client closes the input stream, and on reading end-of-file the server should exit promptly. The spec calls that the primary and only portable signal for graceful shutdown, so handle it honestly and save yourself a pile of process-killing trouble.

The engineering trade-off reads like this: stdio brings zero configuration, zero network attack surface, and process isolation for free; against that, it only serves the local machine, cannot run multiple replicas or be shared with a team, and the server's lifecycle is entirely in the client's hands — the client crashes and your server becomes an orphan process. Serving a team means changing transport, which is day 4's business.

Standing up a server with the official SDK: what registering a tool takes

Yesterday's hand-assembled _meta existed to show you the bottom layer. Nobody does that when actually writing a server, because the SDK already handles transport, message framing, and schema validation.

Registering a tool takes four things: a name, a description written for the model, an input schema, and a body. The output schema and the annotations are optional and should both be written in production.

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'
 
const server = new McpServer({ name: 'weather-fx-server', version: '0.1.0' })
 
server.registerTool(
  'get_weather',
  {
    title: 'Weather lookup', // for humans; the client renders its UI from this
    description:
      "Look up a city's current weather, returning the temperature in Celsius and the conditions. Pass a city name in city, for example Shanghai.",
    inputSchema: {
      city: z.string().min(1).describe('a city name, for example Shanghai or Seattle'),
    },
  },
  async ({ city }) => {
    const hit = await fetchWeather(city)
    return { content: [{ type: 'text', text: JSON.stringify(hit) }] }
  }
)
 
// The transport comes last, and is the one place where changing transport changes one line
await server.connect(new StdioServerTransport())

from mcp.server.mcpserver import MCPServer
 
# Note the 2.x rename: FastMCP is now MCPServer
server = MCPServer(name="weather-fx-server", version="0.1.0")
 
 
@server.tool(
    title="Weather lookup",
    description=(
        "Look up a city's current weather, returning the temperature in Celsius and the "
        "conditions. Pass a city name in city, for example Shanghai."
    ),
)
async def get_weather(city: str) -> dict:
    """city: a city name, for example Shanghai or Seattle"""
    return await fetch_weather(city)
 
 
# The transport comes last, and is the one place where changing transport changes one line
server.run(transport="stdio")

The two shapes are alike: declare the metadata, then write an ordinary function. Python is less work because it can infer the schema from type annotations and the docstring; TypeScript declares it explicitly with zod, which buys compile-time detection of a mistyped parameter name.

Now something slightly uncomfortable has to be said, or following tutorials online will leave you confused throughout. Measured on 2026-09-06: the latest JavaScript @modelcontextprotocol/sdk is 1.30.0, its internal latest-protocol-version constant is still 2025-11-25, and the package contains no resultType and no server/discover. Python's mcp package at 2.1.1 has caught up to 2026-07-28, with the discovery request, the input-required result, and subscription listen requests all present in its types.

The line is one sentence: the spec says this, and current SDKs implement that. A server written with the JS SDK genuinely emits the previous revision's messages on the wire; yesterday's hand-written message is what the spec looks like. That affects none of today's concepts — tools, schemas, annotations, and error classification did not change between revisions — but it affects what you see when capturing traffic. The fastest way to judge whether a piece of material is current is to search it for server/discover and resultType.

The input schema is a contract written for the model

This section is the most valuable of the day, because it decides whether your tool gets called and whether it gets called wrongly.

The description first. A tool description is written for the model, not for a colleague. The model cannot see your wiki, your code comments, or your requirements document — it has only the sentence you wrote. So "look up an order, see the documentation" is the same as writing nothing. An adequate description answers three questions: what this tool does, what the parameters look like (with an example, ideally), and under what circumstances it should be used. That last one is most often omitted and most damaging: without stated applicability, the model calls it when it should not.

Now the schema. MCP's schemas are JSON Schema 2020-12 by default (that is what applies with no $schema). The spec has a set of recommendations for tool names: 1 to 128 characters, using only letters, digits, underscores, hyphens, and dots, case-sensitive, unique within a server, and no spaces or commas. The form for a no-argument tool is worth remembering separately, and this one is recommended:

{
  "name": "get_current_time",
  "description": "Returns the current server time",
  "inputSchema": { "type": "object", "additionalProperties": false }
}

additionalProperties: false means it accepts only an empty object, which is more explicit than a bare { "type": "object" } (which accepts any object). The input schema must be a valid JSON Schema object and cannot be null.

Parameter naming is part of the contract too. city beats q, and start_date beats d1, because the model infers meaning from names and descriptions together. Write a description on every field; the return on that is absurdly high — one sentence on one field often beats three more lines in the overall tool description.

The output schema and structured content: so downstream code stops parsing natural language

Tool returns come in two kinds. Unstructured content goes in content and is text, images, or audio for the model to read; structured content goes in structuredContent and is JSON for code to use.

If you declare an outputSchema, the spec's requirement is hard: the server must return a structured result conforming to that schema, and the client should validate against it. The benefit is direct — downstream code no longer needs a regex to dig the number out of "New York is currently 22 degrees and cloudy."

There is also an easily missed compatibility rule: a tool returning structured content should also return a serialized JSON text copy in content. Older clients recognize only content, and giving them structuredContent alone leaves them with nothing.

server.registerTool(
  'get_weather',
  {
    description: "Look up a city's current weather…",
    inputSchema: { city: z.string().describe('a city name') },
    // Declaring the output shape lets the client validate and spares downstream code from parsing prose
    outputSchema: {
      celsius: z.number().describe('the current temperature in Celsius'),
      conditions: z.string().describe('a description of the conditions'),
    },
  },
  async ({ city }) => {
    const hit = await fetchWeather(city)
    return {
      // Give both: content for older clients, structuredContent for code
      content: [{ type: 'text', text: JSON.stringify(hit) }],
      structuredContent: hit,
    }
  }
)

from typing import TypedDict
 
 
class Weather(TypedDict):
    celsius: float
    conditions: str
 
 
@server.tool(description="Look up a city's current weather…")
async def get_weather(city: str) -> Weather:
    """city: a city name"""
    # The return annotation is the output schema; the SDK fills both content and structuredContent
    return await fetch_weather(city)

The engineering cost: an output schema is an external contract once published, so renaming a field is a breaking change. Do not dump your internal data structure out verbatim from the start — expose only the few fields you are willing to maintain long term. Day 7 returns to this when covering versioning.

The four annotation hints, and why they are untrustworthy

Annotations are a set of behavioural hints attached to a tool definition. The four field names, verified in practice, are readOnlyHint (read-only, changes no external state), destructiveHint (may make a destructive update), idempotentHint (repeating the call with the same arguments is equivalent to calling it once), and openWorldHint (acts on an open external world rather than a closed set), plus a title for display.

What does a client do with them? Mainly decide whether to raise a confirmation dialog and how to mark things in the interface. A read-only, idempotent lookup can run silently; a delete carrying a destructive hint should make the user click to confirm.

But the spec adds a very heavy warning here: a client must treat tool annotations as untrusted input unless they come from a trusted server.

That sentence deserves one more layer of thought. Annotations are written by the server itself, and a malicious server can perfectly well stamp readOnlyHint: true on delete_all_files and fool any client that skips confirmation for read-only tools. So:

Annotations are interface hints, not access control. Real permissions must be set by the host according to the server's provenance, never decided by the server's own account of itself.

That is the same reasoning as yesterday's clientInfo rule — anything the other side reports about itself cannot be used for a security decision. Day 6 unrolls this thread into a full attack surface analysis.

Two classes of error: one for the program to fix, one for the model to correct

The place beginners most often get wrong. MCP tools have two error reporting mechanisms, and using the wrong one traps the model in pointless retries.

Protocol errors go through JSON-RPC's error field. They mean the request itself was wrong: the tool name does not exist, the request fails the schema for calling the tool, the server blew up internally.

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": { "code": -32602, "message": "Unknown tool: invalid_tool_name" }
}

Tool execution errors go through isError: true in the result. They mean the tool ran and did not succeed on business grounds: a downstream API failed, an argument failed a business rule, business logic refused. This is still a successful JSON-RPC response.

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resultType": "complete",
    "content": [{ "type": "text", "text": "The departure date must be later than today. Today is 2026-09-06." }],
    "isError": true
  }
}

The difference is who can fix it. The spec says a client should hand an execution error to the model so it can self-correct and retry; a protocol error may be shown to the model too and is basically useless there. So the criterion is one sentence:

Could the model succeed by changing an argument? If yes, use isError; if no, return a JSON-RPC error.

The corollary is that an execution error's wording is written for the model: list the valid values, the correct format, the boundary conditions. That "Today is 2026-09-06" above is the model of it — it tells the model directly which way to change. Writing "invalid argument" instead leaves the model guessing.

Today's lab has a more insidious counter-example: skipping argument validation so an illegal input computes a NaN and returns silently. No error, no isError, and the model carries that wrong result forward as a correct answer. That is far more dangerous than crashing, because it leaves no trace at all.

Debugging with Inspector: seeing the messages beats guessing

The most painful moment writing a server is "the model just will not call my tool." Two roads open then: tweak the description and try again, purely by superstition; or pull up the messages and look.

There is an official MCP Inspector, a debugging tool that wires a server in, shows messages in both directions one at a time, and triggers tool calls by hand. How to launch it and what its interface looks like are in the official documentation and change with versions, so no commands are copied here. What to remember is the approach: first confirm the tool really appears in tools/list and the schema really is the shape you think, and only then suspect the model. Over half of "the model will not call my tool" turns out to be a tool that never registered, or a misspelled parameter name.

Today's lab ships a lighter substitute: the SDK's in-memory transport wires client and server into one process, running assertions one at a time and printing what happened. It suits continuous integration better than Inspector, because it has a definite exit code. The two are complementary: Inspector for exploring, the self-test entry point for regression.

One last easily overlooked recommendation from the spec: tools/list should return tools in a deterministic order (the same order every time while the underlying tool set is unchanged). The reason is not fussiness — a stable order lets clients cache the tool list reliably, and the model side's prompt cache hits more often too. Generating the list by iterating a hash map casually destroys that optimization.

Source Reading

Hands-On Lab

This lab makes no network calls and needs no API key, with weather and rates both from built-in fake tables. The starter has 5 exercise points cut out, and running it as-is shows 5 ❌ — each one you finish turns one ✅, which is your progress bar. When stuck, read what that item printed; it tells you directly what is missing.

1. Read the solution's src/server.ts first, find tool registration, schema declaration, and transport startup, and confirm each tool is metadata plus an ordinary function.
2. Complete get_weather in the starter: rewrite the perfunctory description into something the model can act on, add the output schema and structuredContent, and run once to see items 1 and 3 go green.
3. Change the unknown-city throw into deliberately returning isError with the available cities in the message, and watch item 4 go green — while feeling how useless a thrown message is to the model.
4. Add argument validation to convert_currency so a negative amount and an unknown currency both return an execution error; note the starter would otherwise silently return a negative result, which is the most dangerous case.
5. Write a set of annotations for each tool, thinking through what the read-only, idempotent, and open-world hints should each say, and get to 7 of 7 ✅.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward writing tool descriptions, schema design, the division between the two error classes, and stdio's boundaries. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Stand up a stdio server with the official SDK, and see its registered tools appear in a client
• Write a usable input schema, output schema, and description for a tool, and explain who the description is written for
• Distinguish protocol errors from tool execution errors, and give an example of when to use each
• Explain why tool annotations must be treated as untrusted input
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D3) we fill in the other two primitives: resources and prompts. The order is again deliberate — a tool is picked by the model while resources and prompts are picked by the application and the user, and a different controlling party means an entirely different design method. And once the data volume rises (a directory of several thousand notes, say), you immediately hit pagination, caching, and change notifications, three things today never touched.