What you’ll build in 90 minutes

A working MCP server is a small program that lets Claude read, write, or call any system you specify — your Notion, your Stripe, your Supabase, your local files. By the end of this tutorial you’ll have a server that exposes your local notes folder to Claude Code, with read and search functions. Total time: 90 minutes. Total cost: $0. Required knowledge: how to open a terminal.

I built my first MCP server in 2 hours after avoiding it for 3 months because the documentation looked dense. The actual work was 12 lines of code I didn’t write — Claude wrote them.

What MCP actually is

MCP (Model Context Protocol) is a standard published by Anthropic in November 2024. It lets any LLM call any tool, the same way USB-C lets any laptop charge from any cable. Before MCP, every integration was custom. After MCP, you write a server once and any MCP-compatible client (Claude Code, Claude.ai, Cursor with MCP plugin) can use it.

There are 600+ public MCP servers as of May 2026. You probably want to write your first one anyway, because the public ones won’t know your weird workflow.

Prerequisites

  • A computer with macOS, Windows, or Linux.
  • Node.js 20+ installed (node --version should print v20 or higher).
  • Claude Code installed (claude --version should print 2.0+).
  • A folder of notes — any markdown files will do. Use ~/notes/ if you have it; otherwise create a folder with 5 random .md files.
  • 90 minutes uninterrupted.

If you don’t have Node.js, install it from nodejs.org (LTS version, takes 4 minutes).

Step 1 — Create the project (5 min)

In your terminal:

mkdir my-first-mcp
cd my-first-mcp
npm init -y
npm install @modelcontextprotocol/sdk

This creates a Node project and installs the official MCP SDK. The SDK handles 90% of the boilerplate.

You should see a package.json and node_modules/ folder. If not, check that Node.js is installed correctly.

Step 2 — Ask Claude Code to scaffold the server (15 min)

Open Claude Code in this folder:

claude

Then paste this prompt:

I want to build an MCP server in TypeScript that exposes a local notes folder
to Claude. It should support two tools:
1. list_notes — returns all .md filenames in /Users/<me>/notes/
2. read_note — takes a filename and returns the file contents

Create server.ts with proper imports from @modelcontextprotocol/sdk.
Use stdio transport. Add error handling. Make it production-quality
but readable for a beginner.

Replace <me> with your username. Claude Code will write the file in 30-60 seconds.

Step 3 — Test the server locally (10 min)

Run it:

npx tsx server.ts

You should see no output. That’s correct — MCP servers communicate via stdin/stdout, not console logs. Press Ctrl+C to stop.

Now configure Claude Code to use it. Open ~/.claude/mcp.json (create it if missing):

{
  "mcpServers": {
    "my-notes": {
      "command": "npx",
      "args": ["tsx", "/full/path/to/my-first-mcp/server.ts"]
    }
  }
}

Replace /full/path/to/ with the absolute path. Restart Claude Code.

Step 4 — Verify it works (5 min)

In Claude Code, type:

Use the my-notes MCP server to list all my notes.

If you see a list of filenames, you’ve shipped your first MCP server. If you see “MCP server not found,” check the path in mcp.json.

Step 5 — Add a search tool (20 min)

Most useful MCP servers go beyond list+read. Ask Claude Code:

Add a third tool to server.ts called search_notes.
It takes a query string and returns the top 5 notes containing that string.
Use simple text matching, no fancy ranking.

Claude Code will edit the file. Run it again, restart Claude Code, then test:

Search my notes for "Q2 planning".

You should see relevant filenames returned.

Step 6 — Add error handling and timeouts (15 min)

Production MCP servers fail gracefully. Ask Claude Code:

Add error handling to server.ts:
1. If the notes folder doesn't exist, return a clear error.
2. If a note can't be read (permissions), return a clear error.
3. Wrap all tool calls in try/catch.
4. Add a 5-second timeout on file reads.

This is where most beginner servers fall over in production.

Step 7 — Document it (10 min)

Create a README.md in your project folder:

# My Notes MCP Server

Exposes a local notes folder to Claude Code.

## Tools
- list_notes — list all .md files
- read_note — read a specific file
- search_notes — search across all notes

## Setup
1. Clone repo
2. npm install
3. Add to ~/.claude/mcp.json with absolute path
4. Restart Claude Code

## License
MIT

This is mandatory if you ever share the server with another founder.

Verification

You should now have:

  1. A working MCP server in server.ts.
  2. Three tools: list_notes, read_note, search_notes.
  3. A configured ~/.claude/mcp.json entry.
  4. A README.md.

If Claude Code can list, read, and search your notes when asked, you’re done.

Common errors and fixes

ErrorCauseFix
”MCP server not found”Wrong path in mcp.jsonUse absolute path, not ~
”Cannot find module”Forgot npm installRun npm install in project folder
”EACCES: permission denied”Notes folder not readableCheck folder permissions
Server starts but no tools appearWrong exportConfirm server.ts exports a Server instance
Timeout on every callNotes folder is hugeAdd file count limit (e.g., max 1,000 files)

What this unlocks

Once you’ve shipped one MCP server, the pattern repeats. I’ve built 4 in the last 3 months:

  1. Notes server — the one above.
  2. Stripe MCP — Claude can pull customer + subscription data into a chat.
  3. Beehiiv MCP — Claude can read newsletter performance and draft sponsorship copy.
  4. Supabase MCP — Claude can query my database read-only without me typing SQL.

Each took 2-4 hours after the first one. The first one taught me the pattern.

The honest truth about MCP in 2026

Most public MCP servers are mediocre. They cover 80% of the use case but miss the 20% that matters for your workflow. Writing your own is the only way to get exact-fit tools, and the entry barrier is much lower than it looks.

The hardest part is sitting down. The actual code is 50-80 lines. Claude writes most of it.

FAQ

Do I need to know TypeScript to write an MCP server?

No. Claude Code writes the TypeScript for you. You need to read it well enough to spot obvious errors, but you can ship a working server without writing a single line yourself.

Can I write an MCP server in Python?

Yes. The MCP Python SDK is at github.com/modelcontextprotocol/python-sdk. The pattern is identical to TypeScript. Pick the language you’re most comfortable reading.

What’s the difference between MCP and a Claude Skill?

Claude Skills run inside Claude as instruction packs. MCP servers run as external processes Claude can call. Use Skills for “give Claude better instructions.” Use MCP for “give Claude access to a system.”

Can my MCP server use API keys?

Yes. Store keys in environment variables (process.env.STRIPE_KEY etc.) and pass them via the env field in mcp.json. Never commit keys to a repo.

How do I share my MCP server with my team?

Publish the repo to GitHub with clear setup instructions, or package it as an npm module. Each team member adds their own entry to mcp.json. There’s no central registry yet, but Anthropic announced one for Q3 2026.

Will MCP servers slow down Claude?

Each tool call adds 100-500ms. For interactive use you won’t notice. For batch jobs, profile and cache where possible. Avoid making your server call slow remote APIs without a timeout.

Can I make money writing MCP servers?

Some founders charge $10-50 one-time for premium MCP servers. The market is small but growing. The bigger leverage is writing internal MCP servers that 10x your own productivity.

Going further