AI Engineer Roadmap All lessons Interactive Quiz GitHub

MCP Server

Beginner · 11 min read · Updated · By Saurabh Pathak

In short: An MCP server is a program that exposes tools, resources and prompts to MCP clients over a transport such as stdio.

Play the interactive lesson: MCP serverRead on GitHub
On this page
  1. Explain it like I'm new
  2. Watch it
  3. How it works
  4. Code example
  5. When to use it / when not to
  6. Common mistakes
  7. Recap
  8. Interview questions
  9. Go deeper

Level: Beginner · Reading time: 11 min · Phase: 6 — MCP

Before you start: Model Context Protocol. You should know that MCP joins an AI app (client) to tools and data (server).

Explain it like I'm new

A server is like a restaurant kitchen with a menu. The menu lists what you can order (tools, resources, prompts). The client is the waiter who carries orders in and dishes out. The kitchen does the real work and does not care which diner asked.

In MCP, "server" does not mean a big machine in the cloud. Most servers are small programs that run on your laptop. The host starts them as child processes and talks to them through stdin and stdout. That is the stdio transport.

Words to know:

Watch it

MCP server: A small program that offers tools, resources and prompts.
MCP server: A small program that offers tools, resources and prompts.

It plays on a loop. Read the caption in the box, one step at a time. Want to go at your own pace? Step through it with Previous and Next.

How it works

  1. The server starts and waits for messages.
  2. It receives initialize with the client's protocol version and capabilities.
  3. It replies with its own version, capabilities (which primitives it supports) and serverInfo.
  4. It receives the notifications/initialized notification. A notification has no id and gets no reply.
  5. It now answers tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get.
  6. Capabilities decide what is allowed. If the server did not declare tools, the client should not call tools.

Two transports

stdioStreamable HTTP
Where it runsLocal child process of the hostAnywhere: local or remote
Message pathJSON-RPC lines on stdin/stdoutHTTP POST (and optional streaming) to one endpoint
AuthInherits your user permissions; credentials via env varsHTTP-level auth; the spec describes OAuth-based authorization
Good forPersonal tools, files, devShared or hosted services

Streamable HTTP replaced the older HTTP+SSE transport. Check the transports page in the current spec for details.

sequenceDiagram
  participant C as Client
  participant S as Server
  C->>S: initialize (version, capabilities)
  S-->>C: result (version, capabilities, serverInfo)
  C->>S: notifications/initialized
  C->>S: tools/list
  S-->>C: result (tools)

Stdio rule: stdout is the protocol channel. Never print() or console.log() there. Log to stderr.

Worked example

Here is what a server does for the first two messages. The lines are real output of the toy in code/mcp_mini_jsonrpc.py.

  1. Client sends initialize with id 1. The server replies with the same id and lists what it supports: tools, resources and prompts.
  2. Client sends notifications/initialized. It has no id, so the server stays silent.
  3. Client sends tools/list with id 2. The server answers with add_numbers and word_count.

The order matters. If a client sends tools/list before the handshake is finished, the toy server replies with an error: code -32600, "Server not initialized".

Code example

The real server in this repo is code/hello-mcp-server/src/index.ts. Its skeleton:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "hello-mcp-server", version: "1.0.0" });
// ... server.registerTool(...) calls go here ...
await server.connect(new StdioServerTransport());
console.error("hello-mcp-server running on stdio"); // stderr, not stdout

The Python version that runs offline is code/mcp_mini_jsonrpc.py. Its MiniMcpServer.handle() takes one JSON string and returns one JSON string (or None for notifications).

SDK version note. I ran this snippet against the official mcp Python package, version 2.3.0 (pip install mcp). In 1.x versions the same class was called FastMCP and lived in mcp.server.fastmcp. The decorators (@tool(), @resource(), @prompt()) are the same. If you pin mcp<2, use from mcp.server.fastmcp import FastMCP. Check the SDK docs for your version.

In real projects (official mcp Python SDK):

from mcp.server.mcpserver import MCPServer

mcp = MCPServer("hello")

@mcp.tool()
def add_numbers(a: float, b: float) -> float:
    """Add two numbers and return the sum."""
    return a + b

if __name__ == "__main__":
    mcp.run()  # stdio by default

When to use it / when not to

Common mistakes

Recap

If you remember only three things:

Interview questions

  1. What happens during initialization?

<details><summary>Answer</summary>The client sends initialize with its version and capabilities. The server replies with its version, capabilities and info. The client then sends notifications/initialized.</details>

  1. Why must a stdio server not write logs to stdout?

<details><summary>Answer</summary>stdout carries the JSON-RPC messages. Extra text breaks parsing. Use stderr.</details>

  1. stdio vs Streamable HTTP?

<details><summary>Answer</summary>stdio is a local child process. Streamable HTTP runs over HTTP and suits remote, shared servers that need real authorization.</details>

Go deeper

Prev: 01-model-context-protocol.md · Next: 03-mcp-client.md · Back to phase: Phase 6