Post

Building Your First MCP Server: From Zero to Expert with TypeScript

Building Your First MCP Server: From Zero to Expert with TypeScript

The AI landscape is evolving rapidly, and one of the most exciting developments is the Model Context Protocol (MCP) – a standardized way for AI assistants like Claude to connect with external tools and data sources. If you’ve ever wanted to extend your AI assistant’s capabilities beyond its built-in knowledge, MCP servers are your gateway to unlimited possibilities.

After diving deep into MCP development and building multiple servers for different use cases, I’ve created a comprehensive hello-world implementation that serves as both a working example and complete learning resource. The project is open-sourced on GitHub at hello-world-mcp-server.

Here’s everything you need to know to go from MCP beginner to expert, with practical examples and real-world insights.

What Makes MCP Special?

Before jumping into code, it’s worth understanding why MCP matters. Traditional AI integrations often require custom APIs, complex authentication, or platform-specific solutions. MCP standardizes this through a simple, protocol-based approach:

  • Universal Protocol: Works with Claude Desktop, Cline, and other MCP-compatible clients
  • Stdio Transport: Simple, secure communication without network configuration
  • Three Core Capabilities: Tools (functions), Resources (data), and Prompts (templates)
  • JSON-RPC Foundation: Battle-tested messaging protocol
  • Easy Development: TypeScript SDK handles protocol complexity

Think of MCP as a universal adapter that lets AI assistants “plug into” any system you can code.

The MCP Server Architecture Challenge

Building MCP servers involves several technical challenges that aren’t immediately obvious:

  • Protocol Compliance: Strict JSON-RPC 2.0 messaging requirements
  • Stdio Interference: Standard output is reserved for protocol messages
  • Type Safety: Input validation and schema definitions
  • Error Handling: Graceful failure without crashing the server
  • Multi-Client Support: Different AI assistants have varying capabilities

The Solution: A Production-Ready Foundation

My approach creates a comprehensive MCP server that demonstrates all three capabilities while providing extensive documentation and examples. You can explore the complete implementation on GitHub, but here are the key architectural decisions:

Project Structure and Setup

The server uses modern TypeScript with ES2020 modules for maximum compatibility:

1
2
3
4
5
6
7
8
9
10
11
// TypeScript configuration optimized for MCP
{
  "compilerOptions": {
    "target": "es2020",
    "module": "es2020", 
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true
  }
}

Core Server Implementation

The server demonstrates all three MCP capabilities in a single, cohesive implementation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  {
    name: "hello-world-mcp-server", 
    version: "1.0.0",
  },
  {
    capabilities: {
      resources: {},
      tools: {},
      prompts: {},
    },
  }
);

For the complete server implementation with all handlers, see the source code.

Key Technical Components

1. Tools Implementation

Tools are executable functions that AI assistants can call. Here’s the pattern I use:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// List available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "hello",
        description: "Returns a greeting message",
        inputSchema: {
          type: "object",
          properties: {
            name: { type: "string", description: "Name to greet" }
          }
        }
      }
    ]
  };
});

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "hello") {
    const nameArg = args?.name as string;
    return {
      content: [{
        type: "text",
        text: nameArg ? `Hello, ${nameArg}!` : "Hello, World!"
      }]
    };
  }
});

2. Resources for Data Access

Resources provide read-only access to data sources:

1
2
3
4
5
6
7
8
9
10
11
server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [{
      uri: "greeting://hello-world",
      name: "Hello World Message", 
      description: "A simple hello world greeting",
      mimeType: "text/plain"
    }]
  };
});

3. Prompts as Templates

Prompts generate structured templates for common tasks:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "greeting-template") {
    const personName = args?.name as string;

    return {
      description: `Personalized greeting for ${personName}`,
      messages: [{
        role: "user",
        content: {
          type: "text", 
          text: `Hello, ${personName}! How can I assist you today?`
        }
      }]
    };
  }
});

Getting Started with the Example

The fastest way to experience MCP development is using the working example:

Quick Setup

1
2
3
4
5
git clone https://github.com/shivprasad/hello-world-mcp-server.git
cd hello-world-mcp-server
npm install
npm run build

Testing with MCP Inspector

1
2
npm run inspect

This launches a web interface where you can:

  • Test all server capabilities interactively
  • View JSON-RPC message flow
  • Debug request/response cycles
  • Validate server behavior

Integration Examples

Claude Desktop Integration

Add to your Claude Desktop configuration:

1
2
3
4
5
6
7
8
9
{
  "mcpServers": {
    "hello-world": {
      "command": "node",
      "args": ["/absolute/path/to/project/dist/index.js"]
    }
  }
}

Cline (VS Code) Integration

For Cline users, the configuration is slightly different:

1
2
3
4
5
6
7
{
  "name": "hello-world-mcp-server",
  "command": "node", 
  "args": ["/absolute/path/to/project/dist/index.js"],
  "env": {}
}

The key difference is using absolute paths and proper environment variable handling.

Advanced Features and Patterns

Input Validation with Zod

The server includes robust input validation:

1
2
3
4
5
6
7
8
9
10
import { z } from "zod";

const HelloArgsSchema = z.object({
  name: z.string().optional(),
  greeting: z.enum(["hello", "hi", "hey"]).default("hello")
});

// Use in tool handlers for type safety
const validatedArgs = HelloArgsSchema.parse(args);

Error Handling Best Practices

Proper error handling prevents server crashes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  try {
    // Tool logic here
  } catch (error) {
    return {
      content: [{
        type: "text",
        text: `Error: ${error.message}`
      }],
      isError: true
    };
  }
});

Multi-Client Compatibility

The server adapts to different AI assistant capabilities:

1
2
3
4
5
6
7
8
9
10
11
12
// Detect client capabilities during initialization
async initialize(clientInfo: any) {
  switch (clientInfo.name) {
    case 'Claude Desktop':
      return { ...baseCapabilities, logging: {} };
    case 'Cline':
      return { ...baseCapabilities, progress: true };
    default:
      return baseCapabilities;
  }
}

Comprehensive Learning Resources

The repository includes extensive documentation designed for different learning styles:

For Beginners

  • README.md: Step-by-step tutorial with complete explanations
  • Setup guides: Environment configuration and dependency management
  • Testing procedures: Using MCP Inspector and AI assistant integration

For Advanced Developers

  • ARCHITECTURE.md: Deep technical dive into MCP internals
  • Advanced patterns: Middleware, plugins, streaming responses
  • Security considerations: Input validation, access control, rate limiting

For Practical Implementation

  • EXAMPLES.md: Real-world use cases and integration patterns
  • Database integration: Safe query execution and data access
  • API connections: External service integration
  • Development workflows: Tools for code testing, linting, documentation

Real-World Applications

After building and testing this foundation, here are some practical MCP servers you could build:

Development Tools

  • Git Integration: Status checking, commit management, branch operations
  • Testing Automation: Running tests, analyzing coverage, generating reports
  • Code Analysis: Linting, dependency checking, security scanning

Business Applications

  • Database Queries: Safe, predefined query execution
  • API Integrations: CRM, marketing platforms, analytics services
  • Document Processing: File conversion, content extraction, template generation

Personal Productivity

  • Task Management: Todo lists, project tracking, time management
  • Content Creation: Blog post templates, social media automation
  • System Monitoring: Server health, application metrics, alert management

Key Insights from Building MCP Servers

Through developing multiple MCP servers, several patterns emerged:

Protocol Mastery is Essential

  • Stdio handling: Never use console.log() in production - it interferes with protocol messages
  • JSON-RPC compliance: Strict adherence to message format requirements
  • Error propagation: Graceful failure handling without server crashes

Type Safety Accelerates Development

  • Schema validation: Use Zod or similar libraries for runtime type checking
  • TypeScript configuration: Proper module resolution for MCP SDK compatibility
  • Interface definitions: Clear contracts between client and server

Documentation Drives Adoption

  • Clear examples: Working code samples for every feature
  • Integration guides: Step-by-step setup for different AI assistants
  • Troubleshooting sections: Common issues and solutions

Testing Strategy Matters

  • MCP Inspector: Essential for development and debugging
  • Multiple clients: Test with both Claude Desktop and Cline
  • Edge cases: Handle missing parameters, network failures, timeout scenarios

Future of MCP Development

The MCP ecosystem is rapidly expanding, with new opportunities emerging:

  • Enterprise Integration: Custom MCP servers for business systems
  • Development Tools: AI-powered coding assistants with MCP backends
  • Data Analysis: Real-time analytics and reporting through MCP
  • Workflow Automation: Complex multi-step processes orchestrated by AI

Conclusion

Building MCP servers opens up unlimited possibilities for AI integration. The key is starting with a solid foundation that demonstrates all capabilities while providing comprehensive learning resources.

The insights from building this hello-world server:

  • Start Simple: Focus on one capability at a time, then combine them
  • Prioritize Documentation: Good docs accelerate both learning and adoption
  • Plan for Multiple Clients: Design for compatibility across AI assistants
  • Test Thoroughly: Use MCP Inspector and real AI assistant integration
  • Think Long-term: Build servers that can evolve with the ecosystem

Whether you’re building internal tools, commercial integrations, or contributing to the open-source ecosystem, MCP provides a powerful foundation for AI-enabled applications.

The complete codebase, documentation, and examples are available at hello-world-mcp-server. Start there, experiment with the examples, and build something amazing.

The future of AI integration is here – and it speaks MCP.

This post is licensed under CC BY 4.0 by the author.