🎯 Sample MCP Servers¶

The MCP Context Forge Gateway includes a collection of high-performance sample MCP servers built in different programming languages. These servers serve multiple purposes: demonstrating best practices for MCP implementation, providing ready-to-use tools for testing and development, and showcasing the performance characteristics of different language ecosystems.

Perfect for testing, learning, and production use - each server is optimized for speed, reliability, and demonstrates language-specific MCP patterns.

🌟 Available Servers¶

🦫 Fast Time Server (Go)¶

mcp-servers/go/fast-time-server - Ultra-fast timezone and time conversion tools

Language: Go 1.21+
Performance: Sub-millisecond response times
Transport: stdio, HTTP, SSE, dual-mode
Tools: get_system_time, timezone conversions with DST support
Container: ghcr.io/ibm/fast-time-server:latest

📖 Full Documentation →

Quick Start¶

# Docker (recommended)
docker run --rm -it -p 8888:8080 \
  ghcr.io/ibm/fast-time-server:latest \
  -transport=dual -log-level=debug

# From source
cd mcp-servers/go/fast-time-server
make build && make run

🚀 Planned Samples¶

🐍 Python Samples¶

Fast Calculator Server - Mathematical operations and conversions
System Info Server - OS and hardware information tools
File Operations Server - Safe file system operations

🟨 JavaScript/TypeScript Samples¶

Web Scraper Server - URL content extraction and parsing
JSON Transformer Server - Data transformation and validation
API Client Server - REST API interaction tools

🦀 Rust Samples¶

High-Performance Parser Server - Ultra-fast text and data parsing
Crypto Utils Server - Cryptographic operations and hashing
Network Tools Server - Network diagnostics and utilities

☕ Java Samples¶

Enterprise Integration Server - Database and messaging operations
Document Processor Server - PDF and office document handling
Monitoring Server - Application metrics and health checks

🎯 Use Cases¶

🧪 Testing & Development¶

Protocol Testing - Validate MCP client implementations
Performance Benchmarking - Compare language runtime characteristics
Integration Testing - Test gateway federation and tool routing

📚 Learning & Reference¶

Best Practices - Language-specific MCP implementation patterns
Architecture Examples - Different transport and authentication approaches
Performance Optimization - Learn optimization techniques per language

🏭 Production Ready¶

Horizontal Scaling - All servers support container orchestration
Monitoring Integration - Built-in health checks and metrics
Security Hardened - Authentication, input validation, and safe defaults

🌐 Gateway Integration¶

All sample servers are designed to integrate seamlessly with the MCP Gateway:

Direct Registration¶

# Register any sample server with the gateway
curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"sample_server","url":"http://localhost:8080/sse"}' \
     http://localhost:4444/gateways

Via Translate Bridge¶

# Expose stdio servers over SSE using mcpgateway.translate
python3 -m mcpgateway.translate \
  --stdio "path/to/sample-server" \
  --expose-sse \
  --port 8002

Testing with Wrapper¶

# Test through mcpgateway.wrapper
export MCP_AUTH=$MCPGATEWAY_BEARER_TOKEN
export MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1'
python3 -m mcpgateway.wrapper

🛠 Development Guidelines¶

Adding New Sample Servers¶

Each sample server should follow these conventions:

Directory Structure¶

mcp-servers/
├── go/
│   └── your-server/
│       ├── main.go
│       ├── Makefile
│       ├── Dockerfile
│       └── README.md
├── python/
│   └── your-server/
│       ├── main.py
│       ├── pyproject.toml
│       ├── Dockerfile
│       └── README.md
└── typescript/
    └── your-server/
        ├── src/index.ts
        ├── package.json
        ├── Dockerfile
        └── README.md

Required Features¶

✅ Multiple transports - stdio, SSE, HTTP support
✅ Container ready - Dockerfile with multi-stage builds
✅ Health checks - /health endpoint for monitoring
✅ Authentication - Bearer token support for web transports
✅ Logging - Configurable log levels
✅ Documentation - Complete usage examples and API docs

Performance Targets¶

Response Time: < 10ms for simple operations
Memory Usage: < 50MB baseline memory footprint
Startup Time: < 1 second cold start
Throughput: > 1000 requests/second under load

📊 Performance Comparison¶

Server	Language	Response Time	Memory	Binary Size	Cold Start
fast-time-server	Go	0.5ms	8MB	12MB	100ms
(planned)	Python	~2ms	25MB	N/A	300ms
(planned)	TypeScript	~3ms	35MB	N/A	400ms
(planned)	Rust	0.3ms	4MB	8MB	50ms
(planned)	Java	~5ms	45MB	25MB	800ms

Benchmarks measured on standard GitHub Actions runners

🤝 Contributing¶

We welcome contributions of new sample servers!

Contribution Process¶

Choose a language and create the directory structure
Implement core MCP functionality following our guidelines
Add comprehensive tests and performance benchmarks
Create documentation following the fast-time-server example
Submit a pull request with your implementation

Language Priorities¶

We're particularly interested in: - Python - Most popular for AI/ML tooling - TypeScript - Web-native integration - Rust - Maximum performance critical applications - Java - Enterprise integration scenarios