Say your team keeps answering the same question from the same internal data: "what's the status of order 4417?", "who owns this service?". You could paste the answer into Claude every time. Or you could write a tiny program that Claude can ask directly. That program is an MCP server, and the first one takes about fifteen minutes.
We'll build the smallest useful server: one tool, count_words, that counts the words in some text. It's deliberately boring, so you can see the shape of a server without any business logic in the way. Swap in your own logic afterwards.
We ran both versions below on 19 November 2026 and listed and called the tool with the MCP Inspector. What we used: Node.js 24.21 with @modelcontextprotocol/server 2.4.0, zod 4.6.7 and TypeScript 7.0.2; Python 3.11.1 with mcp 2.3.0 and uv 0.13.0; MCP Inspector 2.13.0. The official guide asks for Node.js 20 or later, or Python 3.10 or later with Python SDK 2.0.0 or later.
TypeScript
- Create the project and install the SDK:
mkdir word-tools && cd word-tools npm init -y npm install @modelcontextprotocol/server zod npm install -D @types/node typescript npm pkg set type=module scripts.build=tsc mkdir src - Add
tsconfig.json:{ "compilerOptions": { "target": "ES2022", "module": "Node16", "moduleResolution": "Node16", "types": ["node"], "outDir": "./build", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true }, "include": ["src/**/*"] } - Write
src/index.ts(below), then build it withnpm run build.
#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";
// serveStdio calls this whenever it needs a server, so return a new one each time.
function createServer() {
const server = new McpServer({ name: "word-tools", version: "1.0.0" });
server.registerTool(
"count_words",
{
description: "Count the words in a piece of text",
inputSchema: z.object({
text: z.string().describe("The text to count"),
}),
annotations: { readOnlyHint: true },
},
async ({ text }) => {
const words = text.trim() ? text.trim().split(/\s+/).length : 0;
return { content: [{ type: "text", text: `${words} words` }] };
},
);
return server;
}
serveStdio(createServer, {
onerror: (error) => console.error("word-tools error:", error),
});
// Log to stderr: stdout carries the protocol messages.
console.error("word-tools running on stdio");Three lines in there matter more than they look:
- The description and each
.describe()are what the model reads to decide when and how to call your tool. Write them for the model, the way you'd brief a colleague. readOnlyHint: truetells apps the tool changes nothing. ChatGPT, for example, asks the user to confirm every tool that lacks it.- The guide uses
serveStdiobecause it answers both clients on the 2026-07-28 protocol and older ones. A server wired by hand withserver.connect(new StdioServerTransport())only serves the older ones.
Python
Python is shorter, because the SDK reads your function's name, type hints and docstring to describe the tool:
uv init word-tools && cd word-tools
uv add "mcp[cli]"Save this as word_tools.py:
import logging
from mcp.server import MCPServer
# Log to stderr: in a stdio server, stdout carries the protocol messages.
logging.basicConfig(level=logging.INFO)
mcp = MCPServer("word-tools")
@mcp.tool()
def count_words(text: str) -> str:
"""Count the words in a piece of text.
Args:
text: The text to count
"""
return f"{len(text.split())} words"
if __name__ == "__main__":
mcp.run(transport="stdio")Keep the docstring accurate: it becomes the tool's description.
Test it before any app sees it
The MCP Inspector starts your server and talks to it the way an app would. List the tools:
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/listThen call one:
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name count_words --tool-arg 'text=hello there world'For Python, replace node build/index.js with uv run word_tools.py. You should get back 3 words. The Inspector defaults to the older (legacy) protocol era, so run tools/list once with --protocol-era modern and once without to check both.
Use it from Claude
In Claude Code, one command, with the full path to your build:
claude mcp add word-tools -- node /ABSOLUTE/PATH/TO/word-tools/build/index.jsIn Claude Desktop, add this to claude_desktop_config.json and restart the app:
{
"mcpServers": {
"word-tools": {
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/word-tools", "run", "word_tools.py"]
}
}
}Claude Desktop may need the full path to uv or node; find it with which uv (macOS, Linux) or where uv (Windows). The Claude Desktop lesson covers checking and logs.
In short
- A server is a list of tools: a name, a description written for the model, an input schema and a function.
- Local servers talk over stdio: log to stderr, never stdout.
- Test with the MCP Inspector first, then add it to a real app.
What to try next
Share this lesson- Replace
count_wordswith one real task your team asks about, backed by an API you already have. - Publish it to the MCP Registry so apps and directories can find it.
- Read the security checklist before you share it with anyone.