📖 Full Tutorial & Code Walkthrough

Enterprise Model Context Protocol (MCP) Server & Client

A comprehensive enterprise-grade implementation of the Model Context Protocol (MCP) for connecting LLMs with enterprise tools and data sources.

💰 Cost-Optimized for Production

• Zero-cost testing: Works without any LLM API keys
• Optimized models: Uses gpt-4o-mini and claude-3.5-haiku (97% cheaper than premium models)
• Single API key: Choose either OpenAI OR Anthropic (not both)
• Direct tool access: Enterprise functionality without LLM overhead

🚀 Features

MCP Server

• JSON-RPC 2.0 Protocol: Full MCP specification compliance
• Enterprise Tools: Database queries, file operations, API integrations
• Security: JWT authentication, role-based access control
• Monitoring: Prometheus metrics, structured logging
• WebSocket Support: Real-time bidirectional communication

MCP Client

• Multi-LLM Support: OpenAI GPT and Anthropic Claude integration
• Tool Discovery: Automatic detection of server capabilities
• Async Operations: High-performance async/await architecture
• Error Handling: Robust error handling and retry mechanisms

Enterprise Tools

• Database Tool: Secure SQL query execution with injection protection
• File Tool: File system operations with sandboxed access
• API Tool: HTTP client for external API integrations

📦 Installation

Prerequisites

• Python 3.11+
• PostgreSQL (optional, for enterprise database features)
• Redis (optional, for caching and session management)

Quick Start with Docker

# Clone the repository
git clone <repository-url>
cd enterprise_mcp

# Start all services
docker-compose up -d

# The MCP server will be available at ws://localhost:8000/mcp

Manual Installation

Server Setup

cd mcp_server
pip install -r requirements.txt

# Set up environment variables
cp ../.env.example .env
# Edit .env with your configuration

# Run the server
python -m src.mcp_server.main

Client Setup

cd mcp_client
pip install -r requirements.txt

# Set environment variables for LLM APIs (OPTIONAL - choose one or none)
export OPENAI_API_KEY="your-openai-key"      # OR
export ANTHROPIC_API_KEY="your-anthropic-key" # OR neither for zero-cost testing

# Run the demo (with LLM)
python examples/demo.py

# OR run zero-cost demo (no API keys needed)
python examples/demo_no_llm.py

🔧 Configuration

Environment Variables

# Server Configuration
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8000
MCP_SERVER_SECRET_KEY=your-secret-key-here

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/mcp_enterprise
REDIS_URL=redis://localhost:6379

# Authentication
JWT_SECRET_KEY=your-jwt-secret-key
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24

# LLM Configuration (Optional - Cost Optimized)
# Choose ONE API key for cost efficiency:
OPENAI_API_KEY=your-openai-key           # Uses gpt-4o-mini ($0.15/1M tokens)
# OR
ANTHROPIC_API_KEY=your-anthropic-key     # Uses claude-3.5-haiku ($1/1M tokens)

# Enterprise Tools
ENTERPRISE_DB_URL=postgresql://user:password@localhost:5432/enterprise_data
ENTERPRISE_API_BASE_URL=https://api.enterprise.com
ENTERPRISE_API_KEY=your-enterprise-api-key

🎯 Usage Examples

Basic MCP Client Usage

import asyncio
from src.mcp_client.core.client import MCPClient
from src.mcp_client.llm.openai_integration import OpenAIWithMCP

async def main():
    # Initialize MCP client
    mcp_client = MCPClient(
        server_url="ws://localhost:8000/mcp",
        client_info={"name": "My App", "version": "1.0.0"}
    )
    
    # Connect to server
    await mcp_client.connect()
    
    # Initialize LLM with MCP tools
    llm = OpenAIWithMCP(
        api_key="your-openai-key",
        mcp_client=mcp_client
    )
    
    # Use AI with enterprise tools
    messages = [{
        "role": "user",
        "content": "Query the database for user analytics and create a report file"
    }]
    
    result = await llm.chat_completion_with_tools(messages)
    print(result['response'])
    
    await mcp_client.disconnect()

asyncio.run(main())

Database Operations

# Through MCP client
result = await mcp_client.call_tool("database_query", {
    "query": "SELECT COUNT(*) FROM users WHERE created_at > ?",
    "parameters": ["2024-01-01"],
    "limit": 100
})

File Operations

# Create and read files
await mcp_client.call_tool("file_operations", {
    "operation": "write",
    "path": "/tmp/mcp_workspace/report.txt",
    "content": "Enterprise report data..."
})

API Integration

# Make HTTP requests
await mcp_client.call_tool("api_request", {
    "method": "GET",
    "url": "https://api.enterprise.com/metrics",
    "headers": {"Authorization": "Bearer token"}
})

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   LLM Client    │    │   MCP Client    │    │   MCP Server    │
│  (OpenAI/Claude)│◄──►│   (WebSocket)   │◄──►│   (FastAPI)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │ Enterprise Tools │
                                               │ • Database      │
                                               │ • File System   │
                                               │ • APIs          │
                                               └─────────────────┘

🔒 Security Features

• JWT Authentication: Secure token-based authentication
• Role-Based Access Control: Fine-grained permissions
• SQL Injection Protection: Query validation and parameterization
• Sandboxed File Access: Restricted file system operations
• HTTPS/WSS Support: Encrypted communications
• Audit Logging: Comprehensive security event logging

📊 Monitoring

Prometheus Metrics

• mcp_requests_total: Total MCP requests by method and status
• mcp_request_duration_seconds: Request duration histogram
• mcp_active_connections: Current active connections
• mcp_tool_calls_total: Tool execution counts
• mcp_tool_execution_duration: Tool execution time

Health Endpoints

• GET /health: Basic health check
• GET /metrics: Prometheus metrics endpoint

🧪 Testing

# Run server tests
cd mcp_server
pytest tests/

# Run client tests
cd mcp_client
pytest tests/

# Run integration tests
pytest tests/integration/

🚀 Deployment

Production Docker Setup

# Build and deploy
docker-compose -f docker-compose.prod.yml up -d

# Scale the server
docker-compose -f docker-compose.prod.yml up -d --scale mcp-server=3

Kubernetes Deployment

# Apply Kubernetes manifests
kubectl apply -f k8s/

# Check deployment status
kubectl get pods -l app=mcp-server

📈 Performance

• Concurrent Connections: Supports 1000+ simultaneous WebSocket connections
• Request Throughput: 10,000+ requests per second
• Tool Execution: Sub-100ms response time for database queries
• Memory Usage: <512MB per server instance

🛣️ Roadmap

• Redis caching for improved performance
• GraphQL API integration tool
• Enterprise SSO integration
• Multi-tenant support
• Advanced audit and compliance features
• Horizontal auto-scaling

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🙏 Acknowledgments

• Anthropic for the Model Context Protocol specification
• FastAPI for the excellent web framework
• OpenAI and Anthropic for LLM APIs