MCP Template - Build Your Own AI Server
A practical template for creating Model Context Protocol (MCP) servers that enable AI assistants to interact with your data and services.
Overview
This template provides a foundation for building MCP servers - specialized services that AI assistants can connect to for accessing external data, performing operations, and extending their capabilities beyond their training data.
Key Capabilities:
- Expose data as queryable resources
- Provide custom tools for AI assistants to execute
- Handle real-time data operations (CRUD)
- Connect multiple data sources and services
Prerequisites
- Node.js 18+ and npm
- TypeScript knowledge
- Understanding of REST APIs or similar concepts
Quick Start
git clone https://github.com/rhit-bhuwalk/MCP_TEMPLATE.git
cd MCP_TEMPLATE
npm install
npm run build
npm start
This launches a server with sample user data that demonstrates core MCP functionality.
Core Concepts
Resources
Resources represent data collections that AI assistants can query. Think of them as API endpoints that return structured data.
// Register a resource
dataService.registerResource('users', 'User account information');
// AI can now query: "Show me all users" or "Find user with ID 123"
Tools
Tools are functions that AI assistants can execute to perform specific operations on your data.
// Register a tool
server.registerTool(
'create_user',
'Create a new user account',
z.object({
name: z.string(),
email: z.string().email()
}),
async (args) => {
return await dataService.create('mcp://users', args);
}
);
Implementation Guide
1. Define Your Data Structure
Start by defining the shape of your data:
interface Product {
id: string;
name: string;
price: number;
category: string;
inStock: boolean;
}
2. Register Resources
Make your data discoverable to AI assistants:
// In your server setup
dataService.registerResource('products', 'Product inventory data');
// Seed with sample data
const sampleProducts: Product[] = [
{ id: '1', name: 'Laptop', price: 999, category: 'Electronics', inStock: true },
{ id: '2', name: 'Coffee Mug', price: 15, category: 'Kitchen', inStock: false }
];
dataService.seedData('mcp://products', sampleProducts);
3. Add Custom Tools
Create specific operations for your use case:
// Inventory management tool
server.registerTool(
'update_stock_status',
'Update product stock availability',
z.object({
productId: z.string(),
inStock: z.boolean()
}),
async (args) => {
const result = await dataService.update(
'mcp://products',
args.productId,
{ inStock: args.inStock }
);
return { success: true, product: result };
}
);
// Analytics tool
server.registerTool(
'get_category_summary',
'Get inventory summary by category',
z.object({
category: z.string().optional()
}),
async (args) => {
const products = await dataService.queryResource('mcp://products', {
filter: args.category ? { category: args.category } : undefined
});
return {
totalProducts: products.length,
inStock: products.filter(p => p.inStock).length,
outOfStock: products.filter(p => !p.inStock).length,
averagePrice: products.reduce((sum, p) => sum + p.price, 0) / products.length
};
}
);
4. Connect Real Data Sources
Replace in-memory storage with your actual data:
// Example: Connect to a database
class DatabaseDataService extends DataService {
async queryResource(uri: string, query?: any) {
const resourceType = uri.split('://')[1];
switch (resourceType) {
case 'products':
return await this.db.products.findMany({
where: query?.filter || {}
});
case 'orders':
return await this.db.orders.findMany({
include: { items: true }
});
default:
throw new Error(`Unknown resource: ${resourceType}`);
}
}
}
Project Structure
src/
├── core/ # Core MCP server functionality
├── services/ # Data service implementations
├── examples/ # Example implementations
│ └── server.ts # Complete working example
└── index.ts # Main entry point
Start here: src/examples/server.ts contains a complete implementation showing all concepts in practice.
Advanced Patterns
Multi-Resource Operations
server.registerTool(
'process_order',
'Process customer order and update inventory',
z.object({
customerId: z.string(),
productIds: z.array(z.string())
}),
async (args) => {
// Check inventory
const products = await dataService.queryByIds('mcp://products', args.productIds);
// Create order
const order = await dataService.create('mcp://orders', {
customerId: args.customerId,
items: products,
total: products.reduce((sum, p) => sum + p.price, 0)
});
// Update inventory
for (const product of products) {
await dataService.update('mcp://products', product.id, {
inStock: false
});
}
return { orderId: order.id, total: order.total };
}
);
Error Handling and Validation
server.registerTool(
'safe_user_operation',
'Safely perform user operations with validation',
schema,
async (args) => {
try {
// Validate business rules
if (args.email && !isValidEmail(args.email)) {
throw new Error('Invalid email format');
}
const result = await dataService.performOperation(args);
return { success: true, data: result };
} catch (error) {
return {
success: false,
error: error.message,
code: 'VALIDATION_ERROR'
};
}
}
);
Testing Your Server
# Run tests
npm test
# Test with a real AI assistant
npm start
# Connect Claude Desktop or other MCP-compatible client
Deployment Considerations
- Authentication: Add API keys or OAuth for production use
- Rate Limiting: Implement request throttling for high-traffic scenarios
- Data Validation: Always validate inputs from AI assistants
- Logging: Add comprehensive logging for debugging and monitoring
- Error Handling: Provide clear error messages that help AI assistants understand what went wrong
Next Steps
- Examine the examples - Understand the patterns by studying
src/examples/server.ts - Adapt the data models - Replace sample data with your domain objects
- Add domain-specific tools - Create operations that match your business logic
- Connect real data sources - Integrate with databases, APIs, or file systems
- Test with AI assistants - Verify functionality with Claude, ChatGPT, or other MCP clients
This template provides the scaffolding - your domain expertise and data make it valuable.