Simple MCP Server - Learning Edition

A minimal, well-commented MCP (Model Context Protocol) server designed to teach you how MCP servers work.

What is MCP?

Model Context Protocol is a protocol that allows AI models (like Claude) to interact with external systems. Think of it like creating a bridge between Claude and custom tools/services you build.

Claude ←→ MCP Protocol ←→ Your Server

When Claude needs to do something, it can call your server's "tools" instead of being limited to its built-in capabilities.

Related MCP server: Basic MCP Server

Project Structure

mcp-server-example/
├── package.json          # Project configuration and dependencies
├── server.js            # The MCP server (heavily commented!)
└── README.md            # This file

How This Server Works

The 3 Core Components

1. Server Setup (server.js lines 21-28)

   • Creates an MCP server instance

   • Gives it a name and version

2. Tool Definitions (server.js lines 30-80)

   • Each tool has: name, description, and input schema (what parameters it accepts)

   • The description helps Claude understand when to use the tool

   • The input schema validates that Claude provides the right parameters

3. Tool Implementations (server.js lines 90-155)

   • The actual logic that runs when Claude calls a tool

   • Processes the input and returns results

   • Must return a TextContent object with the result

The Three Example Tools

1. add_numbers

Adds two numbers together.

• Input: a (number), b (number)

• Output: The sum

2. format_text

Formats text in different ways.

• Input: text (string), style (uppercase | lowercase | titlecase)

• Output: The formatted text

3. get_current_time

Returns the current date and time.

• Input: None

• Output: Current ISO timestamp

Setting Up and Running

Prerequisites

• Node.js 18+

• npm or yarn

Installation

cd /Users/ythabti/Desktop/mcp-server-example
npm install

Running the Server

npm start

You'll see output like:

[MCP Server] Starting simple learning server...
[MCP Server] Available tools: add_numbers, format_text, get_current_time
[MCP Server] Successfully connected and ready to receive requests!

The server is now running and waiting for Claude to call its tools.

How to Connect This Server to Claude Code

In Claude Code, you can configure this server to be available to Claude by:

1. Create a configuration file for your MCP server

2. Point Claude Code to your server

3. Claude can now call your tools!

Key Concepts to Learn

1. Request Handlers

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  // Handle tool calls here
});

This tells the server what to do when Claude wants to call a tool.

2. Tool Response Format

All tool results must follow this structure:

{
  content: [
    {
      type: "text",
      text: "Your response here"
    }
  ]
}

3. Input Validation

The inputSchema uses JSON Schema to validate what Claude provides:

{
  type: "object",
  properties: {
    parameter_name: {
      type: "string",  // or number, boolean, etc.
      description: "What this parameter does"
    }
  },
  required: ["parameter_name"]
}

4. Error Handling

Return isError: true to signal a failed tool call:

{
  content: [{
    type: "text",
    text: "Error message"
  }],
  isError: true
}

Next Steps - Extending This Server

Try adding these features:

1. Add a Multiply Tool

// Define the tool
const multiplyTool = {
  name: "multiply_numbers",
  description: "Multiplies two numbers",
  inputSchema: {
    type: "object",
    properties: {
      a: { type: "number" },
      b: { type: "number" }
    },
    required: ["a", "b"]
  }
};

// Register it in the tools/list handler
// Add the implementation in the CallToolRequest handler

2. Add a Weather Tool (mock data)

Return fake weather data to understand how tools work with real-world data.

3. Add File Reading Tool

Read files from the system and return their contents.

4. Add Database Tool

Connect to a database (SQLite, PostgreSQL, etc.) and run queries.

Common Mistakes to Avoid

❌ Forgetting to register tools in the tools/list handler ✅ Use the same tool names in definition and implementation

❌ Wrong response format ✅ Always wrap responses in { content: [{type: "text", text: "..."}] }

❌ Not describing tools properly ✅ Clear descriptions help Claude use tools correctly

❌ Missing required fields in schema ✅ Mark all required parameters with "required": ["field1", "field2"]

Debugging Tips

1. Check stderr output

   • The server logs to stderr (console.error) so you can see what's happening

2. Add logging

   • Add console.error() statements to track what tools are being called

3. Test responses

   • Verify your response format matches the expected structure

Resources

• MCP Documentation

• MCP SDK for Node.js

• JSON Schema Reference

Summary

This simple MCP server demonstrates:

• ✅ How to define tools Claude can use

• ✅ How to handle tool calls

• ✅ How to return results in the proper format

• ✅ The basic protocol structure

• ✅ Input validation using JSON schemas

Use this as a foundation to build more complex servers that connect Claude to your custom systems!