​

Hello World MCP Server Tutorial

Welcome to your first MCP (Model Context Protocol) server! This tutorial will walk you through creating a simple “Hello World” MCP server from scratch. Don’t worry if you’ve never built an MCP server before - we’ll explain everything step by step.

​

What You’ll Learn

By the end of this tutorial, you’ll have:

• Created your first working MCP server
• Connected it to an AI assistant
• Understood the basic structure of MCP servers
• Learned how to add simple tools and resources

​

Prerequisites

Before we start, make sure you have:

• Node.js (version 18 or higher) installed on your computer
• npm or pnpm package manager
• A text editor (like VS Code, Sublime Text, or any editor you prefer)
• Basic familiarity with JavaScript/TypeScript (don’t worry, we’ll keep it simple!)

​

Step 1: Set Up Your Project

First, let’s create a new folder for our MCP server and set up the basic project structure.

1. Open your terminal or command prompt
2. Create a new directory and navigate to it:

mkdir my-first-mcp-server
cd my-first-mcp-server

3. Initialize a new Node.js project:

npm init -y

This creates a package.json file with default settings. You should see something like this in your folder now.

​

Step 2: Install MCP Dependencies

Now we need to install the MCP SDK (Software Development Kit) that provides all the tools we need to build our server.

npm install @modelcontextprotocol/sdk

​

Step 3: Create Your First MCP Server

Now for the exciting part - let’s create our actual MCP server! Create a new file called server.js in your project folder:

// server.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

class HelloWorldServer {
  constructor() {
    this.server = new Server(
      {
        name: "hello-world-server",
        version: "1.0.0",
      },
      {
        capabilities: {
          tools: {},
        },
      }
    );

    this.setupToolHandlers();
  }

  setupToolHandlers() {
    // Handle tool listing - this tells AI assistants what tools we have
    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
        tools: [
          {
            name: "say_hello",
            description: "Says hello to a person with a custom message",
            inputSchema: {
              type: "object",
              properties: {
                name: {
                  type: "string",
                  description: "The name of the person to greet",
                },
                message: {
                  type: "string",
                  description: "An optional custom message (defaults to 'Hello')",
                },
              },
              required: ["name"],
            },
          },
        ],
      };
    });

    // Handle tool execution - this is what happens when AI uses our tool
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;

      if (name === "say_hello") {
        const personName = args.name;
        const customMessage = args.message || "Hello";
        
        return {
          content: [
            {
              type: "text",
              text: `${customMessage}, ${personName}! 👋 This is your first MCP server working perfectly!`,
            },
          ],
        };
      }

      throw new Error(`Unknown tool: ${name}`);
    });
  }

  async run() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.error("Hello World MCP server running on stdio");
  }
}

const server = new HelloWorldServer();
server.run().catch(console.error);

​

Step 4: Understanding Your Server Code

Let’s break down what each part of your server does:

​

The Server Setup

this.server = new Server({
  name: "hello-world-server",
  version: "1.0.0",
}, {
  capabilities: {
    tools: {},
  },
});

This creates your MCP server with a name and tells it that it can provide “tools” to AI assistants.

​

Tool Definition

The ListToolsRequestSchema handler tells AI assistants what your server can do. Our server has one tool called say_hello that:

• Takes a person’s name (required)
• Takes an optional custom message
• Returns a greeting

​

Tool Execution

The CallToolRequestSchema handler is what actually runs when an AI assistant uses your tool. It takes the person’s name and message, then returns a friendly greeting.

​

Step 5: Update Your Package.json

We need to tell Node.js that our project uses ES modules. Open your package.json file and add this line:

{
  "name": "my-first-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0"
  }
}

The important addition is "type": "module" which allows us to use modern JavaScript import syntax.

​

Step 6: Test Your Server

Let’s make sure your server works! In your terminal, run:

npm start

You should see:

Hello World MCP server running on stdio

Great! Your server is running. Press Ctrl+C to stop it for now.

​

Step 7: Connect to Pylee

Now let’s connect your server to Pylee so you can use it with AI assistants!

1. Start your server (if it’s not already running):

   Copy

   npm start
   

2. Open Pylee in your web browser and go to the Server Setup page

3. Configure your server:

   • Server Name: My First Hello World Server
   • Connection Type: Choose “Local Connection”
   • Command: node
   • Arguments: server.js
   • Working Directory: The full path to your my-first-mcp-server folder

4. Test the connection using Pylee’s test feature

5. Save your configuration

​

Step 8: Use Your Server with AI

Once connected, you can now use your MCP server with any AI assistant connected to Pylee! Try asking:

“Use the say_hello tool to greet John with a custom message ‘Good morning’”

The AI will use your MCP server and you should get a response like:

“Good morning, John! 👋 This is your first MCP server working perfectly!”

​

What’s Next?

Congratulations! You’ve successfully created and deployed your first MCP server. Here are some ideas to expand your server:

​

Add More Tools

Try adding a new tool to your server. For example, a tool that generates random jokes:

{
  name: "tell_joke",
  description: "Tells a random programming joke",
  inputSchema: {
    type: "object",
    properties: {},
  },
}

​

Add Resources

MCP servers can also provide resources - think of them as files or data that AI assistants can read.

​

Learn Advanced Features

• Server Configuration - Learn about all the configuration options
• Remote Connections - Deploy your server to the cloud
• HTTP vs SSE Transports - Different ways to connect

​

Troubleshooting

​

Common Issues

“Module not found” errors

• Make sure you’ve run npm install
• Check that your package.json includes "type": "module"

“Server won’t start” errors

• Verify your Node.js version is 18 or higher: node --version
• Check for syntax errors in your server.js file

“Connection failed” in Pylee

• Make sure your server is running (npm start)
• Double-check the working directory path in Pylee
• Ensure the command is just node and arguments is server.js

​

Getting Help

If you’re stuck, here are some resources:

• Troubleshooting Guide - Common issues and solutions
• MCP Configuration - Detailed configuration options
• Community Support - Ask questions and get help

​

Summary

You’ve just built your first MCP server! Here’s what you accomplished:

✅ Created a new MCP server from scratch
✅ Added a custom tool that AI assistants can use
✅ Connected it to Pylee
✅ Tested it with an AI assistant

Your server might be simple, but it demonstrates all the core concepts of MCP servers. Every complex MCP server starts with these same basic building blocks.

The most important thing to remember is that MCP servers are just programs that follow a specific protocol to communicate with AI assistants. Once you understand this basic pattern, you can build servers that connect to databases, APIs, file systems, or any other system you can imagine!

Ready to build something more complex? Check out our other MCP server guides to learn advanced techniques and best practices.