starter-mcp-server

Course: MCP & Tool Ecosystems Path: Agentic Coding Path · Position 11

A Gold Standard MCP server scaffold. Three working primitives (tools, resources, prompts) wired to Claude Desktop in under 5 minutes. Extend it with your own tools using the patterns in agent.spec.md.

What Is MCP?

The Model Context Protocol is an open standard that lets Claude (and other AI models) call code you write — fetching data, running calculations, querying databases — without leaving the conversation.

You → Claude → calls your tool → tool runs → result back to Claude → Claude answers you

This server implements MCP over stdio, which means Claude Desktop spawns it as a child process and communicates via stdin/stdout. No HTTP, no ports, no hosting needed.

Quick Start

1. Install and build

npm install
npm run build

2. Find your absolute path

pwd
# → /Users/yourname/projects/starter-mcp-server

3. Configure Claude Desktop

Open (or create) your Claude Desktop config file:

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

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the mcpServers block (replace the path with your real path from step 2):

{
  "mcpServers": {
    "starter-mcp-server": {
      "command": "node",
      "args": ["/Users/yourname/projects/starter-mcp-server/dist/index.js"]
    }
  }
}

See claude_desktop_config.json.example for a full example with environment variables.

4. Restart Claude Desktop

Fully quit and reopen Claude Desktop. Look for the 🔨 hammer icon near the chat input. Click it — you should see starter-mcp-server listed with three tools.

5. Test it

Try asking Claude:

"Use the calculate_sum tool to add 847 and 293."

"Read the system://info resource and tell me how much free memory this machine has."

What's Included

Tools (Claude can call these)

Resources (Claude can read these)

Prompts (appear in Claude's "/" menu)

Development Workflow

Test without Claude Desktop (uses the MCP Inspector UI):

npm run inspect

Watch mode (auto-restarts on file changes):

npm run dev

After editing source files, run npm run build before testing with Claude Desktop. Claude Desktop caches the built output — it reads from dist/, not src/.

Adding Your First Tool

1. Create src/tools/weather.ts — follow the exact pattern in src/tools/math.ts

2. Export weatherTools: Tool[] and handleWeatherTool(name, args): string | null

3. In src/index.ts, add two lines (marked with // ADD NEW ... comments)

4. Run npm run build

5. Restart Claude Desktop

The agent.spec.md file contains a copy-paste prompt you can give to Claude Code to build a complete new tool for you.

File Structure

src/
  index.ts              ← server setup + request routing
  tools/
    math.ts             ← 3 math tools (the pattern to copy)
  resources/
    system.ts           ← 2 system info resources
  prompts/
    index.ts            ← 1 sample prompt
dist/                   ← compiled JS (generated by npm run build)
claude_desktop_config.json.example
.env.example
agent.spec.md           ← AI prompt to extend this server

Critical Rule: Never Use console.log

stdout is reserved for the MCP JSON-RPC protocol. Any console.log() call will corrupt the stream and break Claude Desktop's connection to this server.

Always use console.error() for debug output. It writes to stderr, which is safe.

// ✅ Safe — writes to stderr
console.error("debug:", someValue);

// ❌ Breaks the server — writes to stdout
console.log("debug:", someValue);