spring-mcp-gateway

Spring MCP Gateway

AnSpring Cloud Gateway implementation designed for routing and managing multiple Model Context Protocol (MCP) servers at enterprise scale.

Why Java Over Node.js?

This project demonstrates why Java Spring Cloud Gateway excels for high-volume MCP server routing:

• Performance: 65,000+ requests/second sustained vs Node.js ~18,000 requests/second
• Latency: Java maintains 8ms P95 while Node.js degrades to 45ms+ under load
• Enterprise Security: Production-ready OAuth2, JWT, SAML support out-of-the-box
• Operational Excellence: Superior JVM profiling, monitoring, and debugging capabilities

Prerequisites

• Java 17+
• Maven 3.6+
• An MCP server running locally (optional for testing)

Running the Gateway

# Clone the repository
git clone https://github.com/gmogmzGithub/spring-mcp-gateway.git
cd spring-mcp-gateway

# Build and run
./mvnw spring-boot:run

The gateway will start on http://localhost:8080

Testing the Routes

# Test public route (no auth required)
curl http://localhost:8080/test/anything

# Test authenticated MCP route
curl -u mcpuser:password123 http://localhost:8080/mcp/anything

# Test admin route
curl -u mcpadmin:admin123 http://localhost:8080/admin/anything

# Test calculator MCP server (if running on localhost:8050)
curl -u mcpuser:password123 http://localhost:8080/calculator/sse

Configuration

Adding Your MCP Server

1. Update routing configuration in src/main/java/com/indeed/mcp/gateway/config/GatewayRoutingConfig.java:

.route("your-mcp-server", r -> r
    .path("/your-server/**")
    .filters(f -> f
        .stripPrefix(1)
        .addRequestHeader("X-MCP-Gateway", "true"))
    .uri("http://your-mcp-server:port"))

2. Configure security in src/main/java/com/indeed/mcp/gateway/config/SecurityConfig.java:

.pathMatchers("/your-server/**").authenticated()

3. Test your integration:

curl -u mcpuser:password123 http://localhost:8080/your-server/endpoint

Security Configuration

The gateway includes three security levels:

• Public Routes (/test/**) - No authentication required
• Authenticated Routes (/mcp/**, /calculator/**) - Valid user required
• Admin Routes (/admin/**) - Admin role required

Default users:

• mcpuser:password123 (USER role)
• mcpadmin:admin123 (USER, ADMIN roles)

Docker Deployment

# Build the application
./mvnw clean package

# Build Docker image
docker build -t spring-mcp-gateway .

# Run container
docker run -p 8080:8080 spring-mcp-gateway

Architecture

Client Request → Spring Cloud Gateway → MCP Server
                       ↓
                Security Filters
                Routing Rules
                Request/Response Transformation

Key Components

• GatewayRoutingConfig - Route definitions and filters
• SecurityConfig - Authentication and authorization
• Application Properties - Gateway and security settings

Performance Benchmarks

Tested with Apache JMeter on AWS EC2 instances:

Metric	Java Spring Gateway	Node.js Express
Requests/sec	65,000+	~18,000
P95 Latency	8ms	45ms+
Memory Usage	Stable	Gradual increase
CPU Usage	60%	85%+

Results may vary based on hardware and configuration

Development

Adding Features

1. Custom Filters - Implement GatewayFilter for request/response transformation
2. Health Checks - Use Spring Actuator endpoints for monitoring
3. Metrics - Integrate Micrometer for performance monitoring
4. OAuth2 - Uncomment OAuth2 configuration in application.properties

Testing

# Run all tests
./mvnw test

# Run with coverage
./mvnw test jacoco:report

Production Considerations

Security Hardening

• Replace in-memory users with database/LDAP integration
• Enable HTTPS with proper certificates
• Configure CORS for browser-based clients
• Implement rate limiting and DDoS protection

License

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

Related Articles

• Java vs Node.js for MCP Gateways: A Performance Analysis - LinkedIn Article
• Building Enterprise AI Gateways with Spring Cloud - Technical Deep Dive

Support

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions

---

⭐ Star this repository if it helps with your MCP server management!