toy-mcp-server

A minimal Model Context Protocol (MCP) server built from scratch to learn how MCP actually works — no boilerplate generators, no templates, just the SDK.

Built as a first hands-on MCP project: two tools and one resource, wired into Claude Desktop over stdio.

What it does

MCP lets an LLM client (like Claude Desktop) call functions running on your own machine, instead of only generating text from its training data. This server exposes:

Tools (functions Claude can call):

• roll_dice — rolls N dice with a configurable number of sides

• flip_coin — flips a coin N times

Resources (read-only data Claude can fetch):

• server-info — basic metadata about the server (name, purpose, start time)

Related MCP server: Random-Generator

Why this exists

LLMs can't access anything outside their own training data, and can't do anything by default — they only generate text. MCP is a standard way to give a model:

• capability it doesn't have on its own (e.g. true randomness — LLMs are notoriously bad at picking random numbers themselves)

• access to live or private data it has no way of knowing

This project is a small, safe sandbox for that idea before pointing an MCP server at something real (a database, an API with auth, etc.).

Tech stack

• TypeScript

• @modelcontextprotocol/sdk — official MCP SDK

• zod — runtime schema validation for tool arguments

• stdio transport (local subprocess communication with Claude Desktop)

Project structure

toy-mcp-server/
├── src/
│   └── index.ts       # server setup, tools, and resource
├── build/              # compiled output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

Setup

1. Install dependencies

npm install

2. Build

npm run build

3. Connect to Claude Desktop

Find your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: usually under %LOCALAPPDATA%\Packages\<Claude package folder>\LocalCache\Roaming\Claude\claude_desktop_config.json — the exact path can vary by install method (Microsoft Store vs. direct installer). The reliable way to find it: open Claude Desktop → Settings → Developer → Local MCP servers → Edit Config, which opens the exact file the app reads.

Add this server under mcpServers (merge into the existing file rather than overwriting it):

{
  "mcpServers": {
    "toy-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/toy-mcp-server/build/index.js"]
    }
  }
}

Replace the path with the actual absolute path to build/index.js on your machine. On Windows, escape backslashes (\\) in the JSON string.

4. Restart Claude Desktop

Fully quit (not just close the window) and reopen. Check Settings → Developer → Local MCP servers to confirm toy-mcp-server shows as connected.

5. Try it

In a chat, ask:

• "Roll 3 six-sided dice"

• "Flip a coin 10 times"

You should see a small tool-call indicator (e.g. "Roll Dice") above the response, confirming Claude actually invoked the function rather than guessing an answer.

How it works, briefly

• McpServer — the object that declares the server's capabilities to any connecting client

• registerTool(name, config, handler) — registers a callable function. config.inputSchema uses Zod to validate whatever arguments the model sends before the handler runs

• registerResource(name, uri, config, handler) — registers read-only data addressable by a URI, fetched without arguments

• StdioServerTransport — the wire format: Claude Desktop spawns this file as a subprocess and communicates over stdin/stdout using JSON-RPC. console.log is never used for logging here, since stdout is the actual protocol channel — console.error (stderr) is used instead

Next steps

• Swap the toy tools for real ones hitting an actual database (Postgres via Prisma)

• Add a GitHub-backed tool (e.g. list_open_prs) to practice token-based auth

• Explore Streamable HTTP transport to host this remotely instead of running it locally

License

MIT