Creating Your First MCP Server

A production-ready TypeScript implementation of a Model Context Protocol (MCP) server with example tools demonstrating best practices for building MCP servers.

Quick Start

Installation

npm install

Build

npm run build

Run the Server

npm start

Run Example Client

npm run example

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It enables:

• Standardized Communication: A unified way for LLMs to interact with external tools and data sources
• Tool Integration: Expose custom functionality that AI models can discover and use
• Resource Management: Provide structured access to files, databases, and APIs
• Prompt Templates: Define reusable prompts for common tasks

Key MCP Concepts

1. Server: Exposes tools, resources, and prompts that clients can use
2. Client: Connects to MCP servers to access their capabilities
3. Tools: Executable functions that perform specific tasks
4. Resources: Data sources like files, database records, or API endpoints
5. Prompts: Reusable prompt templates with parameters

Project Structure

creating-your-first-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── tools/
│       ├── calculator.ts      # Mathematical operations tool
│       ├── weather.ts         # Weather information tool
│       └── file-ops.ts        # File operations tool
├── examples/
│   └── client.ts             # Example MCP client usage
├── documentation/
│   ├── MCP-CONCEPTS.md       # In-depth MCP concepts
│   ├── TOOL-DEVELOPMENT.md   # Guide to creating tools
│   └── INTEGRATION.md        # Integration guide
├── package.json
├── tsconfig.json
└── LICENSE

Available Tools

Calculator Tool

Performs mathematical operations (add, subtract, multiply, divide, power, sqrt).

// Example usage
{
  "operation": "add",
  "a": 5,
  "b": 3
}
// Returns: { "result": 8 }

Weather Tool

Retrieves weather information for a location (simulated data for demonstration).

// Example usage
{
  "location": "San Francisco"
}
// Returns weather data including temperature, conditions, humidity

File Operations Tool

Performs file system operations (read, write, list, delete).

// Example usage
{
  "operation": "read",
  "path": "/path/to/file.txt"
}
// Returns file contents or operation result

Development

Building

npm run build

Watch Mode

npm run dev

Clean Build Artifacts

npm run clean

Documentation

For more detailed information, see:

• MCP Concepts - Deep dive into MCP architecture and concepts
• Tool Development Guide - How to create custom tools
• Integration Guide - Integrating the server with clients

Error Handling

This server implements comprehensive error handling:

• Input validation for all tool parameters
• Graceful error messages for clients
• Type-safe error responses
• Logging for debugging

Security Considerations

• File operations are restricted to safe directories
• Input validation prevents injection attacks
• Error messages don't expose sensitive system information
• Rate limiting can be added for production use

License

MIT License - Copyright (c) 2026 ry-ops

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Resources

• MCP Specification
• MCP SDK Documentation
• TypeScript Documentation