Skip to content

Apache Knox extension that aggregates multiple Model Context Protocol (MCP) servers into a single REST API endpoint

License

Notifications You must be signed in to change notification settings

lmccay/knox-mcp-proxy

Repository files navigation

Knox MCP Proxy

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.

๐ŸŒŸ Overview

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.

โœจ Key Features

  • ๐Ÿ”— 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

๐Ÿ—๏ธ Architecture

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 Support Matrix

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

โš™๏ธ Configuration

Knox Topology Setup

<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>

Supported Endpoint Formats

  • stdio://command args - Subprocess-based MCP servers (Python, Node.js, etc.)
  • http://host:port - Standard HTTP request/response MCP servers
  • https://host:port - Secure HTTP MCP servers
  • sse://host:port - Standard SSE bidirectional MCP servers
  • sses://host:port - Secure SSE MCP servers
  • custom-http-sse://host:port - Knox-optimized hybrid transport
  • custom-https-sse://host:port - Secure Knox hybrid transport

๐Ÿ”’ Security Configuration

Stdio Command Allowlist

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>

๐Ÿ“š API Reference

๏ฟฝ MCP Streamable HTTP Endpoint (Specification Compliant)

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 responses
  • X-Session-ID: <session-id> - Used for routing messages to SSE sessions

๏ฟฝ๐Ÿ” Discovery Endpoints

# 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

โšก Execution Endpoints

# 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 Endpoints (Backward Compatibility)

โš ๏ธ DEPRECATED but fully supported for existing clients:

# 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

๐Ÿ’ก Usage Examples

Multi-Transport Configuration

<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>

API Usage

# 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

๐Ÿ› ๏ธ Development

Prerequisites

  • Java 8+ (compatible with Knox 1.6.1)
  • Maven 3.6+
  • Apache Knox 1.6.1+

Build & Test

# Clean build
mvn clean compile

# Run comprehensive test suite  
mvn test

# Package for deployment
mvn package

Installation

  1. Build the JAR: mvn package
  2. Deploy to Knox: Copy target/knox-mcp-proxy-1.0.0-SNAPSHOT.jar to Knox's ext/ directory
  3. Configure Topology: Add MCP service configuration
  4. Restart Knox: Restart the Knox gateway service

Project Structure

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

๐ŸŽฏ Implementation Highlights

๐Ÿ”ง Complete Transport Support

  • 4 transport protocols with full MCP standard compliance
  • Automatic protocol detection based on endpoint URLs
  • Seamless fallback and error handling per transport type

๐Ÿš€ Production Features

  • 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

๐Ÿ›ก๏ธ Enterprise Security

  • Knox authentication integration
  • Role-based authorization for tools and resources
  • Audit logging for all MCP operations
  • SSL/TLS termination through Knox

โšก Performance Optimized

  • Connection reuse and persistent connections where appropriate
  • Request batching and response caching
  • Resource cleanup and memory management
  • Configurable timeouts and retry logic

๐Ÿ“Š Comparison with Official MCP SDK

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

๐Ÿ”ฎ Advanced Features

Custom Transport Protocol

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

Tool & Resource Namespacing

{
  "calculator.add": {
    "description": "Add two numbers",
    "server": "calculator"
  },
  "webapi.weather": {
    "description": "Get weather data", 
    "server": "webapi"
  }
}

Health Monitoring

{
  "status": "healthy",
  "servers": {
    "calculator": {"status": "connected", "tools": 5, "resources": 2},
    "webapi": {"status": "connected", "tools": 12, "resources": 8}
  },
  "total_tools": 17,
  "total_resources": 10
}

๐Ÿค 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 branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

๐Ÿ“„ License

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

๐Ÿ”— Related Projects


๐ŸŽ‰ Ready to aggregate your MCP ecosystem through Knox? Start with the Configuration section above!

About

Apache Knox extension that aggregates multiple Model Context Protocol (MCP) servers into a single REST API endpoint

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •