Sample MCP Servers

🎯 Sample MCP Servers

The ContextForge 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 ContextForge:

!!! tip "Gateway URL" - Direct installs (uvx, pip, or docker run): http://localhost:4444 - Docker Compose (nginx proxy): http://localhost:8080

Direct Registration

# Set the gateway base URL
export BASE_URL="http://localhost:4444"
# export BASE_URL="http://localhost:8080"  # docker-compose with nginx

# 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"}' \
     $BASE_URL/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="$BASE_URL/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

Benchmarks measured on standard GitHub Actions runners

🤝 Contributing

We welcome contributions of new sample servers!

Contribution Process

1. Choose a language and create the directory structure
2. Implement core MCP functionality following our guidelines
3. Add comprehensive tests and performance benchmarks
4. Create documentation following the fast-time-server example
5. 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

📚 Resources

MCP Specification

• Model Context Protocol
• JSON-RPC 2.0 Specification

Gateway Documentation

• ContextForge Gateway
• mcpgateway.wrapper Usage
• mcpgateway.translate Bridge

Development Tools

• MCP Inspector - Interactive protocol debugging
• mcpgateway.translate Bridge - stdio ↔ SSE/Streamable HTTP bridge
• UV - Fast Python package management

🔗 Quick Links

• 🦫 Fast Time Server (Go) →

Want to add a new sample server? Open an issue or submit a pull request!