Building Your First MCP Server
Step by step: build, test, and connect a working MCP server in TypeScript that exposes your own tools to any agent.
Connecting other people's MCP servers is useful. Building your own is where things get interesting. Your company's internal API, your personal notes, the obscure tool your team depends on that no vendor will ever write an integration for: with a small MCP server, every one of them becomes something any agent can use, in Claude Code, Cursor, Claude Desktop, VS Code, Codex, and more.
It's less work than you might expect. In this lesson you'll build a complete, working MCP server in TypeScript with the official SDK: three tools, a resource, and a prompt, wrapped around a folder of Markdown notes. You'll test it with the MCP Inspector, connect it to Claude Code and other agents, and learn the handful of details (logging, input validation, error messages) that separate a server that works on your machine from one that works reliably.
What you'll build
You're going to build notes, an MCP server that gives agents access to a folder of Markdown notes. It exposes:
| Capability | Type | What it does |
|---|---|---|
search_notes | Tool | Finds notes containing a word or phrase and shows the matching lines |
read_note | Tool | Returns a note's full contents |
add_note | Tool | Creates a new note, refusing to overwrite an existing one |
notes://index | Resource | A list of every note file |
weekly_review | Prompt | A template that asks the agent to research a topic across your notes |
It's deliberately simple, so the MCP parts stay in focus. But the shape (a few well-designed tools around a data source, with safe defaults) is exactly what real internal servers look like. Once it works, swapping the notes folder for your company's API is mostly a matter of changing what's inside each tool.
Prerequisites: Node.js 22 or later (check with node --version), a terminal, and a code editor. If you've never written TypeScript, you can follow along by pasting the code exactly, or have a coding agent do the typing while you read along.