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.