A comprehensive Apache Knox extension that aggregates multiple Model Context Protocol (MCP) servers into a unified MCP gateway, providing seamless access to distributed AI tools and resources with full transport compatibility.
Knox MCP Proxy extends Apache Knox to serve as a central gateway for MCP ecosystems. It provides a Jersey-based REST API and MCP Server that connects to multiple downstream MCP servers using any transport protocol and exposes their aggregated capabilities through secure, authenticated HTTP endpoints.
- ๐ Universal MCP Compatibility: Supports ALL MCP transport protocols (stdio, HTTP, SSE, custom)
- ๏ฟฝ MCP Streamable HTTP Compliant: Implements official MCP specification with unified endpoint and content negotiation
- ๏ฟฝ๐ Multi-Server Aggregation: Seamlessly combines tools and resources from multiple MCP servers
- ๐ก๏ธ Knox Security Integration: Leverages Knox's authentication, authorization, and security providers
- ๐ท๏ธ Intelligent Namespacing: Prevents tool/resource conflicts with server-prefixed names
- ๐ Backward Compatibility: Maintains full compatibility with existing SSE clients while adding spec compliance
AI Agents & Applications
|
v
Knox Gateway (Security, Auth, SSL)
|
v
Jersey REST API (/mcp/v1/*)
|
v
MCP Proxy Resource (Aggregation)
|
โโโ stdio://python calculator_server.py (Process)
โโโ http://webapi.example.com (HTTP)
โโโ sse://realtime.service.com (SSE)
โโโ custom-http-sse://gateway.internal (Custom)
Transport | Endpoint Format | Compatible With | Best For |
---|---|---|---|
stdio | stdio://python server.py |
Standard MCP subprocess servers | Local Python/Node.js tools |
HTTP | http://localhost:3000 |
Standard MCP HTTP servers | Stateless web services |
SSE | sse://localhost:4000 |
Standard MCP SSE servers | Real-time applications |
Custom HTTP+SSE | custom-http-sse://localhost:5000 |
Knox-optimized servers | Multi-client gateways |
<service>
<role>MCPPROXY</role>
<name>mcp</name>
<version>1.0.0</version>
<param>
<name>mcp.servers</name>
<value>calculator:stdio://python /path/to/calculator_server.py,
webapi:http://localhost:3000,
realtime:sse://localhost:4000,
gateway:custom-http-sse://localhost:5000</value>
</param>
</service>
stdio://command args
- Subprocess-based MCP servers (Python, Node.js, etc.)http://host:port
- Standard HTTP request/response MCP servershttps://host:port
- Secure HTTP MCP serverssse://host:port
- Standard SSE bidirectional MCP serverssses://host:port
- Secure SSE MCP serverscustom-http-sse://host:port
- Knox-optimized hybrid transportcustom-https-sse://host:port
- Secure Knox hybrid transport
To protect against remote code execution, stdio-based MCP servers are restricted to an allowlist of permitted commands:
<param>
<n>mcp.stdio.allowed.commands</n>
<value>python,node,java,npm</value>
</param>
Security Features:
- โ Command Validation: Only allowlisted commands can be executed
- โ
Path Protection: Commands are validated by base name only (e.g.,
/usr/bin/python
โpython
) - โ Default Security: If no allowlist is configured, a warning is logged
- โ Clear Error Messages: Blocked commands receive descriptive error responses
Example Secure Configuration:
<service>
<role>MCPPROXY</role>
<n>mcp</n>
<version>1.0.0</version>
<param>
<n>mcp.servers</n>
<value>calculator:stdio://python /opt/mcp/calculator.py</value>
</param>
<param>
<n>mcp.stdio.allowed.commands</n>
<value>python,node</value>
</param>
</service>
The Knox MCP Proxy now supports the official MCP Streamable HTTP specification with unified endpoints:
# MCP-compliant unified endpoints
GET /gateway/sandbox/mcp/v1/ # Service info or SSE connection
POST /gateway/sandbox/mcp/v1/ # JSON-RPC requests
# Content negotiation examples:
# 1. Establish SSE connection (streamable mode)
GET /gateway/sandbox/mcp/v1/
Accept: text/event-stream
# Returns: SSE stream with session management
# 2. Standard JSON-RPC request/response
POST /gateway/sandbox/mcp/v1/
Content-Type: application/json
Accept: application/json
{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}
# 3. JSON-RPC with streaming response (requires active SSE session)
POST /gateway/sandbox/mcp/v1/
Content-Type: application/json
Accept: text/event-stream
X-Session-ID: mcp-sse-12345
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {"name": "calculator", "arguments": {"operation": "add", "a": 5, "b": 3}},
"id": 2
}
MCP Protocol Headers:
mcp-version: 2024-11-05
- Automatically added to all responsesX-Session-ID: <session-id>
- Used for routing messages to SSE sessions
# List all available tools across all servers
GET /gateway/sandbox/mcp/v1/tools
# List all available resources across all servers
GET /gateway/sandbox/mcp/v1/resources
# Health check for all connected servers
GET /gateway/sandbox/mcp/v1/health
# Execute a tool with parameters
POST /gateway/sandbox/mcp/v1/tools/{serverName.toolName}
Content-Type: application/json
{
"param1": "value1",
"param2": "value2"
}
# Access a resource
GET /gateway/sandbox/mcp/v1/resources/{serverName.resourceName}
# Legacy SSE endpoint
GET /gateway/sandbox/mcp/v1/sse
# Still works exactly as before - delegates to unified endpoint
# Legacy JSON-RPC endpoint
POST /gateway/sandbox/mcp/v1/message
# Still works exactly as before - includes MCP version headers
# All existing REST endpoints remain unchanged
GET /gateway/sandbox/mcp/v1/tools
GET /gateway/sandbox/mcp/v1/resources
POST /gateway/sandbox/mcp/v1/tools/{toolName}
GET /gateway/sandbox/mcp/v1/resources/{resourceName}
GET /gateway/sandbox/mcp/v1/health
Migration Guide:
- Existing clients (Goose Desktop Agent, etc.) continue working unchanged
- New implementations should use the unified
GET/POST /
endpoint - Legacy endpoints log deprecation warnings but remain fully functional
<param>
<name>mcp.servers</name>
<value>
python_tools:stdio://python /opt/mcp/python_server.py,
web_services:http://api.internal.com:8080,
live_data:sse://streaming.service.com:4000,
legacy_system:custom-http-sse://legacy.gateway.com:9000
</value>
</param>
# Discover available tools
curl -X GET https://knox.company.com/gateway/prod/mcp/v1/tools
# Call a Python-based calculator tool
curl -X POST https://knox.company.com/gateway/prod/mcp/v1/tools/python_tools.calculate \
-H "Content-Type: application/json" \
-d '{"expression": "2 + 2 * 3"}'
# Access a web service API
curl -X POST https://knox.company.com/gateway/prod/mcp/v1/tools/web_services.weather \
-H "Content-Type: application/json" \
-d '{"location": "San Francisco", "units": "metric"}'
# Read real-time data
curl -X GET https://knox.company.com/gateway/prod/mcp/v1/resources/live_data.stock_prices
- Java 8+ (compatible with Knox 1.6.1)
- Maven 3.6+
- Apache Knox 1.6.1+
# Clean build
mvn clean compile
# Run comprehensive test suite
mvn test
# Package for deployment
mvn package
- Build the JAR:
mvn package
- Deploy to Knox: Copy
target/knox-mcp-proxy-1.0.0-SNAPSHOT.jar
to Knox'sext/
directory - Configure Topology: Add MCP service configuration
- Restart Knox: Restart the Knox gateway service
src/main/java/org/apache/knox/mcp/
โโโ McpProxyResource.java # Main REST API resource
โโโ McpServerConnection.java # Connection management
โโโ client/ # Transport implementations
โ โโโ McpJsonRpcClient.java # - stdio transport
โ โโโ McpHttpClient.java # - standard HTTP transport
โ โโโ McpSseClient.java # - standard SSE transport
โ โโโ McpCustomHttpSseClient.java # - Knox custom transport
โ โโโ McpTool.java # - Tool model
โ โโโ McpResource.java # - Resource model
โ โโโ McpException.java # - Exception handling
โโโ deploy/
โโโ McpProxyServiceDeploymentContributor.java # Knox integration
- 4 transport protocols with full MCP standard compliance
- Automatic protocol detection based on endpoint URLs
- Seamless fallback and error handling per transport type
- Java 8 compatibility - no Java 17+ requirement like official SDK
- Asynchronous processing with CompletableFuture
- Connection pooling and lifecycle management
- Comprehensive error handling and graceful degradation
- Real-time monitoring via health check endpoints
- Knox authentication integration
- Role-based authorization for tools and resources
- Audit logging for all MCP operations
- SSL/TLS termination through Knox
- Connection reuse and persistent connections where appropriate
- Request batching and response caching
- Resource cleanup and memory management
- Configurable timeouts and retry logic
Feature | Official MCP SDK | Knox MCP Proxy |
---|---|---|
Java Version | Java 17+ | Java 8+ |
Transports | stdio, HTTP, SSE | stdio, HTTP, SSE, custom HTTP+SSE |
Multi-server | Manual | Automatic aggregation |
Security | None | Knox enterprise security |
Gateway Features | None | Load balancing, SSL, auth |
Production Ready | Basic | Enterprise grade |
Knox Integration | None | Native |
Our Knox-optimized custom-http-sse://
transport provides:
- HTTP POST for requests (stateless, scalable)
- Server-Sent Events for responses (real-time, persistent)
- Message correlation via request IDs
- Multi-client optimization for gateway scenarios
{
"calculator.add": {
"description": "Add two numbers",
"server": "calculator"
},
"webapi.weather": {
"description": "Get weather data",
"server": "webapi"
}
}
{
"status": "healthy",
"servers": {
"calculator": {"status": "connected", "tools": 5, "resources": 2},
"webapi": {"status": "connected", "tools": 12, "resources": 8}
},
"total_tools": 17,
"total_resources": 10
}
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to branch (
git push origin feature/amazing-feature
) - Open a Pull Request
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- Apache Knox - Enterprise gateway for Hadoop clusters
- Model Context Protocol - Standard protocol for AI tool integration
- MCP Java SDK - Official Java implementation
๐ Ready to aggregate your MCP ecosystem through Knox? Start with the Configuration section above!