VereskLearn

Module 7 · MCP

Lesson 7.2

A stdio server with tools

A stdio server reads JSON lines from standard input and writes its replies to standard output.

Lesson 46 of 622 min read

The problem

Why it matters

Without it

Each tool is wired into one app by hand. The app must know every tool name and every input format.

With it

The server lists its tools and runs them on request. Any client that speaks the protocol can use them.

How it works

  • Lines in, lines out

    The host starts the server as a child process. It writes one JSON line per request to standard input. The server writes one JSON line per reply to standard output.

    1. Host writes a line
    2. Standard input
    3. Handler runs
    4. Standard output
    5. Host reads a line
    One request and its reply, through the two text streams.

  • tools/list names the tools

    A tools/list request asks which tools exist. The reply carries their names in a list, so the client can show them to the model. The sample has one tool, get_order.

    const tools: Record<string, unknown> = { get_order: () => "" };const reply = { id: 1, result: { tools: Object.keys(tools) } };console.log(JSON.stringify(reply));

    Output

    {"id":1,"result":{"tools":["get_order"]}}

  • tools/call runs a handler

    A tools/call request names a tool and passes its arguments. The handler returns text, which goes into a content list. For A-1042, the sample returns the text Order A-1042 shipped.

    const tools: Record<string, (id: string) => string> = {  get_order: (id) => "Order " + id + " shipped.",};const text = tools.get_order("A-1042");const content = [{ type: "text", text }];console.log(JSON.stringify({ id: 2, result: { content } }));

    Output

    {"id":2,"result":{"content":[{"type":"text","text":"Order A-1042 shipped."}]}}

  • An unknown method gets an error

    A ping request is not in the sample, so the server returns an error. The code -32601 means method not found. The error reply still carries the id of the request it answers.

    IdMethodReply
    1tools/listtools: get_order
    2tools/calltext: Order A-1042 shipped.
    3pingerror -32601, method not found
    Three requests and the replies the server gives.

Full code

Read the program

See the full code

Common mistakes

What goes wrong

  • Writing logs to standard output. Log lines there corrupt the message stream, so write logs to standard error.
  • Printing a reply across several lines. The client reads one line as one message.
  • Dropping the id. Without it, the client cannot match the reply to its request.

Use it when and skip it when

Is it the right tool?

Use it when

  • The tool runs on the same machine as the host.
  • You want a simple server with no network setup.

Skip it when

  • Many users must reach one server over a network. Use the HTTP transport instead.

Words to know

Terms in this lesson

Standard input
The text stream a program reads, here one JSON line per message.
Standard output
The text stream a program writes to, here one JSON line per reply.
Handler
The function that runs one tool.
Stdio
Short for standard input and standard output.
Full code