ServerAvatar Logo
Start Free Trial

Create MCP Server in Node.js: Step-by-Step Guide

  • Author: Suresh Ramani
  • Published: 9 September 2025
  • Last Updated: 10 September 2025
MCP Server Node.js

Table Of Contents

Have you ever wondered how modern applications communicate seamlessly with each other? Think of an MCP server as a digital translator that helps different software systems have meaningful conversations. Just like how a skilled interpreter bridges language barriers between people from different countries, an MCP (Model Context Protocol) server bridges the gap between AI models and various tools or data sources.

In today’s interconnected world, building robust server applications isn’t just a luxury – it’s a necessity. Whether you’re a seasoned developer or someone just starting their coding journey, understanding how to create an mcp server in Node.js will open doors to countless possibilities. This comprehensive guide will walk you through every step, ensuring you have the knowledge and confidence to build your own MCP server from scratch.

What is an MCP Server and Why Should You Care?

An MCP server is essentially a specialized application that implements the Model Context Protocol, enabling AI models to interact with external tools, databases, and services. But why should this matter to you as a developer?

Imagine you’re building a smart assistant that needs to check the weather, send emails, and analyze data from your company’s database. Without an mcp server, you’d need to hardcode each integration separately. With MCP, your AI assistant can dynamically discover and use available tools through a standardized protocol.

Key Benefits of MCP Servers

Standardization: MCP provides a unified way for AI models to interact with external resources, eliminating the need for custom integrations for each tool or service.

Flexibility: Your server can expose multiple tools and capabilities, allowing AI models to choose the most appropriate ones for specific tasks.

Scalability: As your application grows, you can easily add new tools and capabilities without restructuring your entire system.

Understanding the Model Context Protocol

Before diving into code, let’s understand what makes MCP special. The Model Context Protocol is like a universal language that AI models and tools use to communicate. It defines how requests are made, how responses are structured, and how errors are handled.

Core MCP Concepts

Tools: These are functions that the AI model can call to perform specific actions, like searching a database or making an API request.

Resources: Static or dynamic content that the AI model can access, such as files, documents, or data streams.

Prompts: Pre-defined templates that help structure interactions between the AI model and your server.

Think of MCP as the postal system for AI interactions – it ensures messages get delivered to the right place in the right format, every time.

Setting Up Your Development Environment

Getting started with building an mcp server requires the right tools and environment. Let’s set up everything you need for a smooth development experience.

Prerequisites

Before we begin, make sure you have:

Node.js (version 16 or higher): This is the runtime environment for our server. If you want to upgrade your node.js read this guide for upgrade node.js.

npm or yarn: Package manager for installing dependencies

A code editor: VS Code, Sublime Text, or your preferred editor 

Git: For version control (optional but recommended)

Creating Your Project Directory

Start by creating a new directory for your MCP server project:

Bash
mkdir my-mcp-server
cd my-mcp-server
npm init -y

This creates a basic Node.js project structure with a package.json file that will track your dependencies and project metadata.

Installing Required Dependencies

Now let’s install the packages we’ll need to build our mcp server. Think of these dependencies as the building blocks – each one serves a specific purpose in creating a robust server application.

Essential Dependencies

Bash
npm install @modelcontextprotocol/sdk
npm install express cors helmet
npm install --save-dev nodemon typescript @types/node
npm install -D tsx

@modelcontextprotocol/sdk: The official MCP SDK that provides all the tools we need Express: Web framework for handling HTTP requests CORS: Enables cross-origin resource sharing Helmet: Adds security headers to protect your server Development dependencies: Tools that help during development

Setting Up TypeScript Configuration

Create a tsconfig.json file to configure TypeScript:

JSON
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ES2020",
    "moduleResolution": "node",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "ts-node": {
    "esm": true
  }
}

Creating Your First MCP Server Structure

Let’s build the foundation of your mcp server. Like constructing a house, we need a solid structure before adding the fancy features.

Basic Server Setup

Create a src directory and add your main server file:

TypeScript
// src/server.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

class MyMCPServer {
  private server: Server;

  constructor() {
    this.server = new Server(
      {
        name: 'my-mcp-server',
        version: '1.0.0',
      },
      {
        capabilities: {
          tools: {},
          resources: {},
        },
      }
    );
  }

  async start() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.log('MCP Server started successfully!');
  }
}

const server = new MyMCPServer();
server.start().catch(console.error);

This basic structure creates an mcp server that can start and listen for connections, though it doesn’t do much yet.

Implementing Core Server Functionality

Now comes the exciting part – adding functionality to your mcp server. Let’s implement the core features that will make your server useful.

Adding Your First Tool

Tools are the heart of any MCP server. Let’s add a simple calculator tool:

TypeScript
// Add this to your server class constructor
this.server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'calculate',
        description: 'Perform basic mathematical calculations',
        inputSchema: {
          type: 'object',
          properties: {
            operation: { type: 'string', enum: ['add', 'subtract', 'multiply', 'divide'] },
            a: { type: 'number' },
            b: { type: 'number' }
          },
          required: ['operation', 'a', 'b']
        }
      }
    ]
  };
});

this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === 'calculate') {
    const { operation, a, b } = args as any;
    let result: number;
    
    switch (operation) {
      case 'add': result = a + b; break;
      case 'subtract': result = a - b; break;
      case 'multiply': result = a * b; break;
      case 'divide': result = b !== 0 ? a / b : NaN; break;
      default: throw new Error('Invalid operation');
    }
    
    return {
      content: [
        {
          type: 'text',
          text: `The result of ${a} ${operation} ${b} is ${result}`
        }
      ]
    };
  }
  
  throw new Error('Tool not found');
});

Understanding Tool Implementation

When you implement tools in your mcp server, you’re essentially creating functions that AI models can call. Each tool needs:

A clear name: Something descriptive like ‘calculate’ or ‘search-database’ A detailed description: This helps the AI understand when to use the tool An input schema: Defines what parameters the tool expects Implementation logic: The actual code that performs the work

Adding Tool Integration Capabilities

Your mcp server becomes truly powerful when it can integrate with external services. Let’s add some real-world functionality.

File System Tool

TypeScript
// Add a file reading tool
this.server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      // ... existing tools
      {
        name: 'read-file',
        description: 'Read contents of a text file',
        inputSchema: {
          type: 'object',
          properties: {
            path: { type: 'string', description: 'Path to the file' }
          },
          required: ['path']
        }
      }
    ]
  };
});

// Implementation
import * as fs from 'fs/promises';

// In your CallToolRequestSchema handler
if (name === 'read-file') {
  const { path } = args as { path: string };
  
  try {
    const content = await fs.readFile(path, 'utf-8');
    return {
      content: [{
        type: 'text',
        text: content
      }]
    };
  } catch (error) {
    return {
      content: [{
        type: 'text',
        text: `Error reading file: ${error.message}`
      }],
      isError: true
    };
  }
}

API Integration Tool

Adding external API capabilities makes your mcp server even more versatile. For production-grade applications, you might also want to explore advanced deployment options and server management techniques. You can find comprehensive guides on modern deployment strategies at the official Node.js documentation for best practices and performance optimization.

TypeScript
// Weather API tool example
{
  name: 'get-weather',
  description: 'Get current weather for a location',
  inputSchema: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name' }
    },
    required: ['city']
  }
}

// Implementation
if (name === 'get-weather') {
  const { city } = args as { city: string };
  
  try {
    const response = await fetch(`https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHER_API_KEY}&q=${city}`);
    const data = await response.json();
    
    return {
      content: [{
        type: 'text',
        text: `Weather in ${city}: ${data.current.temp_c}°C, ${data.current.condition.text}`
      }]
    };
  } catch (error) {
    return {
      content: [{
        type: 'text',
        text: `Error fetching weather: ${error.message}`
      }],
      isError: true
    };
  }
}

Handling Client Connections and Communication

Communication is key in any relationship, and the same applies to your mcp server. Let’s ensure your server can handle multiple clients gracefully.

Connection Management

Your MCP server needs to handle client connections properly. Here’s how to implement robust connection handling:

TypeScript
class MyMCPServer {
  private clients: Set<any> = new Set();

  async handleNewConnection(transport: any) {
    this.clients.add(transport);
    
    transport.onClose(() => {
      this.clients.delete(transport);
      console.log('Client disconnected');
    });
    
    console.log(`Client connected. Total clients: ${this.clients.size}`);
  }
}

Message Processing

Your mcp server should process messages efficiently and respond appropriately:

TypeScript
private async processMessage(message: any) {
  try {
    // Log incoming messages for debugging
    console.log('Received message:', JSON.stringify(message, null, 2));
    
    // Process the message based on its type
    switch (message.method) {
      case 'tools/list':
        return await this.handleListTools();
      case 'tools/call':
        return await this.handleCallTool(message.params);
      default:
        throw new Error(`Unknown method: ${message.method}`);
    }
  } catch (error) {
    console.error('Error processing message:', error);
    throw error;
  }
}

Error Handling and Validation

Nobody likes crashes, especially in production servers. Let’s make your mcp server bulletproof with proper error handling and validation.

Input Validation

TypeScript
import Joi from 'joi';

const toolCallSchema = Joi.object({
  name: Joi.string().required(),
  arguments: Joi.object().required()
});

private validateToolCall(params: any) {
  const { error, value } = toolCallSchema.validate(params);
  if (error) {
    throw new Error(`Invalid tool call parameters: ${error.details[0].message}`);
  }
  return value;
}

Graceful Error Responses

Your mcp server should always provide helpful error messages:

TypeScript
private handleError(error: Error, context: string) {
  console.error(`Error in ${context}:`, error);
  
  return {
    content: [{
      type: 'text',
      text: `I encountered an error while ${context}: ${error.message}`
    }],
    isError: true
  };
}

Timeout Handling

Prevent your server from hanging on long-running operations:

TypeScript
private async withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
  return Promise.race([
    promise,
    new Promise<never>((_, reject) => 
      setTimeout(() => reject(new Error('Operation timed out')), timeoutMs)
    )
  ]);
}

Testing Your MCP Server

Testing is crucial for any reliable mcp server. Let’s set up comprehensive testing to ensure your server works correctly.

Unit Testing Setup

TypeScript
npm install --save-dev jest @types/jest ts-jest

Create a test file:

TypeScript
// tests/server.test.ts
import { MyMCPServer } from '../src/server';

describe('MCP Server', () => {
  let server: MyMCPServer;
  
  beforeEach(() => {
    server = new MyMCPServer();
  });
  
  test('should calculate addition correctly', async () => {
    const result = await server.callTool('calculate', {
      operation: 'add',
      a: 5,
      b: 3
    });
    
    expect(result.content[0].text).toContain('8');
  });
  
  test('should handle division by zero', async () => {
    const result = await server.callTool('calculate', {
      operation: 'divide',
      a: 10,
      b: 0
    });
    
    expect(result.content[0].text).toContain('NaN');
  });
});

Integration Testing

Test your mcp server with real MCP clients:

TypeScript
// tests/integration.test.ts
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

describe('MCP Server Integration', () => {
  test('should handle client connection', async () => {
    const server = new MyMCPServer();
    const transport = new StdioServerTransport();
    
    await expect(server.connect(transport)).resolves.not.toThrow();
  });
});

Advanced Configuration Options

As your mcp server grows, you’ll need more sophisticated configuration options. Let’s explore advanced settings that give you greater control.

Environment-Based Configuration

TypeScript
// src/config.ts
export interface ServerConfig {
  port: number;
  environment: 'development' | 'production' | 'test';
  logLevel: 'debug' | 'info' | 'warn' | 'error';
  timeout: number;
  maxConnections: number;
}

export const config: ServerConfig = {
  port: parseInt(process.env.PORT || '3000'),
  environment: (process.env.NODE_ENV as any) || 'development',
  logLevel: (process.env.LOG_LEVEL as any) || 'info',
  timeout: parseInt(process.env.TIMEOUT || '30000'),
  maxConnections: parseInt(process.env.MAX_CONNECTIONS || '100')
};

Tool Configuration

Make your tools configurable:

TypeScript
// src/tools/config.ts
export interface ToolConfig {
  calculator: {
    precision: number;
    maxValue: number;
  };
  fileSystem: {
    allowedPaths: string[];
    maxFileSize: number;
  };
  weather: {
    apiKey: string;
    cacheDuration: number;
  };
}

const toolConfig: ToolConfig = {
  calculator: {
    precision: 2,
    maxValue: Number.MAX_SAFE_INTEGER
  },
  fileSystem: {
    allowedPaths: ['/tmp', '/uploads'],
    maxFileSize: 1024 * 1024 * 10 // 10MB
  },
  weather: {
    apiKey: process.env.WEATHER_API_KEY || '',
    cacheDuration: 5 * 60 * 1000 // 5 minutes
  }
};

Security Best Practices

Security should never be an afterthought when building an mcp server. Let’s implement essential security measures to protect your server and users.

Authentication and Authorization

TypeScript
// src/auth/middleware.ts
export class AuthMiddleware {
  private validTokens = new Set<string>();
  
  validateToken(token: string): boolean {
    return this.validTokens.has(token);
  }
  
  requireAuth(handler: Function) {
    return async (request: any) => {
      const token = request.headers?.authorization?.replace('Bearer ', '');
      
      if (!token || !this.validateToken(token)) {
        throw new Error('Unauthorized: Invalid or missing token');
      }
      
      return await handler(request);
    };
  }
}

Input Sanitization

Protect your mcp server from malicious inputs:

TypeScript
import validator from 'validator';

function sanitizeString(input: string): string {
  return validator.escape(input.trim());
}

function validateFilePath(path: string): boolean {
  // Prevent directory traversal attacks
  return !path.includes('..') && !path.includes('~');
}

Rate Limiting

Prevent abuse of your server:

TypeScript
class RateLimiter {
  private requests = new Map<string, number[]>();
  
  checkRateLimit(clientId: string, limit: number, windowMs: number): boolean {
    const now = Date.now();
    const clientRequests = this.requests.get(clientId) || [];
    
    // Remove old requests outside the window
    const validRequests = clientRequests.filter(time => now - time < windowMs);
    
    if (validRequests.length >= limit) {
      return false; // Rate limit exceeded
    }
    
    validRequests.push(now);
    this.requests.set(clientId, validRequests);
    return true;
  }
}

Performance Optimization Techniques

A slow mcp server can frustrate users and waste resources. Let’s optimize your server for peak performance.

Caching Strategies

Implement intelligent caching to reduce response times:

TypeScript
// src/cache/manager.ts
class CacheManager {
  private cache = new Map<string, { data: any, expiry: number }>();
  
  set(key: string, data: any, ttlMs: number = 60000) {
    this.cache.set(key, {
      data,
      expiry: Date.now() + ttlMs
    });
  }
  
  get(key: string): any | null {
    const entry = this.cache.get(key);
    
    if (!entry || Date.now() > entry.expiry) {
      this.cache.delete(key);
      return null;
    }
    
    return entry.data;
  }
}

// Usage in your tools
const cacheManager = new CacheManager();

if (name === 'get-weather') {
  const cacheKey = `weather:${city}`;
  let weatherData = cacheManager.get(cacheKey);
  
  if (!weatherData) {
    weatherData = await fetchWeatherFromAPI(city);
    cacheManager.set(cacheKey, weatherData, 5 * 60 * 1000); // 5 minutes
  }
  
  return weatherData;
}

Connection Pooling

For database connections and external APIs:

TypeScript
// src/db/pool.ts
import { Pool } from 'pg';

class DatabaseManager {
  private pool: Pool;
  
  constructor() {
    this.pool = new Pool({
      host: process.env.DB_HOST,
      port: parseInt(process.env.DB_PORT || '5432'),
      database: process.env.DB_NAME,
      user: process.env.DB_USER,
      password: process.env.DB_PASSWORD,
      max: 20, // Maximum number of connections
      idleTimeoutMillis: 30000,
      connectionTimeoutMillis: 2000
    });
  }
  
  async query(text: string, params?: any[]) {
    const client = await this.pool.connect();
    try {
      return await client.query(text, params);
    } finally {
      client.release();
    }
  }
}

Asynchronous Processing

Handle heavy workloads without blocking:

TypeScript
// src/queue/processor.ts
class TaskQueue {
  private queue: Array<{ task: Function, resolve: Function, reject: Function }> = [];
  private processing = false;
  
  async add<T>(task: () => Promise<T>): Promise<T> {
    return new Promise((resolve, reject) => {
      this.queue.push({ task, resolve, reject });
      this.process();
    });
  }
  
  private async process() {
    if (this.processing || this.queue.length === 0) return;
    
    this.processing = true;
    
    while (this.queue.length > 0) {
      const { task, resolve, reject } = this.queue.shift()!;
      
      try {
        const result = await task();
        resolve(result);
      } catch (error) {
        reject(error);
      }
    }
    
    this.processing = false;
  }
}

Deployment Strategies

Your mcp server is ready for the world! Let’s explore different deployment options to get your server running in production.

Docker Deployment

Create a Dockerfile for containerized deployment:

Dockerfile
# Dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/

EXPOSE 3000

USER node

CMD ["node", "dist/server.js"]

Environment Configuration

Create different environment files:

Plaintext
# .env.production
NODE_ENV=production
PORT=3000
LOG_LEVEL=info
DB_HOST=production-db.example.com
WEATHER_API_KEY=your-production-key

# .env.development
NODE_ENV=development
PORT=3001
LOG_LEVEL=debug
DB_HOST=localhost
WEATHER_API_KEY=your-dev-key

Process Management

Use PM2 for production process management:

JavaScript
// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'mcp-server',
    script: 'dist/server.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    error_file: './logs/err.log',
    out_file: './logs/out.log',
    log_file: './logs/combined.log'
  }]
};

Troubleshooting Common Issues

Even the best mcp server can encounter problems. Here’s how to diagnose and fix common issues.

Connection Problems

TypeScript
// Debug connection issues
private debugConnection(transport: any) {
  transport.onError((error: Error) => {
    console.error('Transport error:', error);
    this.reconnect();
  });
  
  transport.onClose(() => {
    console.log('Connection closed, attempting reconnect...');
    setTimeout(() => this.reconnect(), 5000);
  });
}

private async reconnect() {
  try {
    await this.start();
    console.log('Reconnected successfully');
  } catch (error) {
    console.error('Reconnection failed:', error);
    setTimeout(() => this.reconnect(), 10000);
  }
}

Memory Management

Monitor and manage memory usage:

JavaScript
// Memory monitoring
setInterval(() => {
  const usage = process.memoryUsage();
  console.log('Memory usage:', {
    rss: Math.round(usage.rss / 1024 / 1024) + 'MB',
    heapUsed: Math.round(usage.heapUsed / 1024 / 1024) + 'MB',
    heapTotal: Math.round(usage.heapTotal / 1024 / 1024) + 'MB'
  });
  
  // Alert if memory usage is too high
  if (usage.heapUsed > 500 * 1024 * 1024) { // 500MB
    console.warn('High memory usage detected!');
  }
}, 30000);

Logging and Debugging

Implement comprehensive logging:

TypeScript
// src/utils/logger.ts
import winston from 'winston';

export const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' }),
    new winston.transports.Console({
      format: winston.format.simple()
    })
  ]
});

Github Repository: srvrsoorg/my-mcp-server

Conclusion

Congratulations! You’ve just learned how to build a comprehensive mcp server in Node.js from the ground up. We’ve covered everything from basic setup to advanced deployment strategies, giving you the tools and knowledge needed to create robust, scalable MCP servers.

Remember, building a great mcp server is like learning to cook – you start with basic recipes and gradually add your own flavors and techniques. The foundation we’ve built here will serve you well as you expand your server’s capabilities and tackle more complex use cases.

Your mcp server is now ready to bridge the gap between AI models and the tools they need to be truly useful. Whether you’re building internal tools for your team or creating public APIs for the broader developer community, the principles and patterns we’ve discussed will help you create servers that are secure, performant, and maintainable.

Keep experimenting, keep learning, and most importantly, keep building amazing things with your new mcp server skills!

Frequently Asked Questions (FAQs)

What exactly is an MCP server and how does it differ from a regular web server?

An mcp server is specifically designed to implement the Model Context Protocol, which enables AI models to interact with external tools and resources. Unlike regular web servers that primarily handle HTTP requests from browsers, an MCP server facilitates communication between AI models and various tools, databases, or services through a standardized protocol. Think of it as a specialized translator that helps AI understand and use external capabilities.

Do I need extensive Node.js experience to build an MCP server?

While basic Node.js knowledge is helpful, you don’t need to be an expert to build a functional mcp server. The MCP SDK handles much of the complexity for you. If you understand JavaScript fundamentals, can work with async/await patterns, and are comfortable with package management, you’ll be able to follow this guide successfully. The key is starting simple and gradually adding more sophisticated features as you learn.

Can my MCP server handle multiple AI models simultaneously?

Absolutely! A well-designed mcp server can handle multiple client connections simultaneously, whether they’re different AI models or multiple instances of the same model. The server manages each connection independently, so one client’s operations won’t interfere with another’s. Just ensure you implement proper connection management and consider resource usage when dealing with many concurrent clients.

How do I secure my MCP server against unauthorized access?

Security for your mcp server involves multiple layers: implement authentication tokens to verify client identity, use input validation to prevent malicious data, apply rate limiting to prevent abuse, sanitize all inputs to avoid injection attacks, and use HTTPS for encrypted communication. Additionally, limit file system access to specific directories and regularly update your dependencies to patch security vulnerabilities.

What’s the best way to debug issues with my MCP server?

Effective debugging of an mcp server starts with comprehensive logging – log all incoming requests, outgoing responses, and any errors that occur. Use structured logging with different levels (debug, info, warn, error) so you can adjust verbosity as needed. Implement health check endpoints to monitor server status, use debugging tools like Node.js inspector for step-through debugging, and create unit tests for individual components. Most importantly, test with real MCP clients to identify integration issues early.

Deploy your first application in 10 minutes, Risk Free!

Learn how ServerAvatar simplifies server management with intuitive dashboards and automated processes.
Get Started Now
  • No CC Info Required
  • Free 4-Days Trial
  • Deploy in Next 10 Minutes!