knox-mcp-proxy

Name: knox-mcp-proxy
Availability: InStock
Author: lmccay

Knox MCP Proxy is an extension of Apache Knox that aggregates multiple Model Context Protocol (MCP) servers into a unified REST API gateway. It provides seamless access to distributed AI tools and resources, supporting all MCP transport protocols. By leveraging Knox's security features, it ensures secure connections through authentication and authorization.

GitHub

GitHub Stars

User Rating

Not Rated

Forks

Issues

Views

Favorites

README

Knox MCP Proxy

A comprehensive Apache Knox extension that aggregates multiple Model Context Protocol (MCP) servers into a unified REST API 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 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)
🚀 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

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

📚 API Reference

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

💡 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

Build the JAR: mvn package
Deploy to Knox: Copy target/knox-mcp-proxy-1.0.0-SNAPSHOT.jar to Knox's ext/ directory
Configure Topology: Add MCP service configuration
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
}