Tutorial 1: Build Your First MCP Server

Build a complete MCP server from scratch that manages a simple note-taking system. You'll learn MCP fundamentals by implementing resources, tools, and prompts.

Time: 45-60 minutes Level: Beginner Prerequisites: Node.js 16+, TypeScript basics, Claude Code installed

---

What You'll Build

A note-taking MCP server with:

• Resources: Access saved notes by ID
• Tools: Create, update, delete notes
• Prompts: Reusable templates for common tasks
• Storage: Simple file-based persistence

Features:

• List all notes
• Get specific note by ID
• Create new notes
• Update existing notes
• Delete notes
• Search notes by keyword

---

Step 1: Project Setup

Create Project Directory

Initialize npm Project

Install Dependencies

Configure TypeScript

Create tsconfig.json:

Update package.json

Create Source Directory

---

Step 2: Implement Note Storage

Create src/notes.ts:

---

Step 3: Implement MCP Server

Create src/index.ts:

---

Step 4: Build and Test

Build the Server

Test Locally (Standalone)

The server will start and wait for MCP requests via stdio.

---

Step 5: Configure Claude Code

Add to Claude Code Settings

Edit ~/.claude/settings.json:

Replace /path/to/ with your actual project path!

---

Step 6: Use with Claude Code

Start Claude Code

Test Resource Listing

Create a Note

List Notes

Read a Note

Search Notes

---

Step 7: Extend the Server (Exercises)

Exercise 1: Add Tags

Add tagging support to notes:

• Add tags: string[] to Note interface
• Implement add_tag and remove_tag tools
• Implement search_by_tag tool

Exercise 2: Add Categories

Organize notes into categories:

• Add category: string to Note
• Implement category management
• Filter resources by category

Exercise 3: Add Export

Export notes to markdown files:

• Implement export_note tool
• Export to specified directory
• Support batch export

---

Troubleshooting

Issue: "Cannot find module"

Solution:

Issue: "Notes not persisting"

Solution: Check file permissions and path in notes.ts:

Issue: "Tool not found"

Solution: Verify tool name matches exactly in both definition and handler.

---

Next Steps

Congratulations! You've built your first MCP server.

What you learned:

• ✅ MCP server architecture
• ✅ Implementing resources
• ✅ Creating tools
• ✅ Handling requests
• ✅ File-based storage
• ✅ Integration with Claude Code

Continue learning:

1. Best Practices - Production patterns
2. Tutorial 2: Database MCP Server
3. MCP Use Cases - Real-world applications

---

Complete Code Repository

Find the complete code at: github.com/examples/mcp-notes-server

---

← Back to Tutorials | MCP Overview →