MCPBlade

MCPBlade is a powerful aggregation and management service for Model Control Protocol (MCP) servers. It provides intelligent tool discovery, semantic search, and smart routing capabilities to seamlessly work with multiple MCP servers.

Features

• Tool Aggregation: Combines tools from multiple MCP servers into a unified interface
• Semantic Search: Vector-based search to find tools using natural language queries
• Smart Routing: Automatically routes tool calls to the correct backend server
• Health Monitoring: Continuous health checks and heartbeat monitoring for all connected servers
• Persistent & Temporary Servers: Support for both persistent configuration-based and temporary runtime servers
• Multiple Transport Types: Support for stdio, SSE, and streamable HTTP transports for backend connections
• NATS Integration: Distributed service communication via NATS messaging with microservices support
• HTTP API: RESTful API and MCP-compatible streaming endpoints
• Middleware Architecture: Logging, proxy, and other middleware support

Architecture

MCPBlade consists of several key components:

• Core Service (service.go): Main business logic and MCP server management
• Vector Search (vector/): Tool indexing and semantic search capabilities
• Transport Layer:
  • transport/nats/: NATS-based communication
  • transport/http/: HTTP API endpoints
• Persistence (persistence/chromem/): Vector database implementation
• MCP Integration (mcp/): MCP protocol endpoint handlers
• Proxy Layer (proxy.go): Service proxy middleware for distributed deployments

Installation

go install github.com/flarexio/mcpblade/cmd/mcpblade@latest
go install github.com/flarexio/mcpblade/cmd/mcpblade_mcp_server@latest

Configuration

Create a configuration file config.yaml (see config.example.yaml for reference):

mcpServers:
  time:
    transport: stdio
    command: uvx
    args: [ "mcp-server-time", "--local-timezone=Asia/Taipei" ]
cacheRefreshTTL: 5m
vector:
  enabled: true
  persistent: true
  collection: tools

Supported Transport Types

• stdio: Standard input/output communication with subprocess
• sse: Server-Sent Events over HTTP
• streamable-http: HTTP streaming protocol

Usage

Running the Core Service

# Run with default configuration path (~/.flarex/mcpblade)
mcpblade

# Run with custom configuration path
mcpblade --path /path/to/config

# Enable HTTP API
mcpblade --http --http-addr :8080

# Connect to custom NATS server
mcpblade --nats nats://localhost:4222

Running as MCP Server

# Connect to shared MCPBlade instance
mcpblade_mcp_server --edge-id your-edge-id

# Run dedicated server with specific MCP backend
mcpblade_mcp_server --edge-id your-edge-id --server-id my-server --cmd "uvx mcp-server-time"

# Connect to custom NATS server
mcpblade_mcp_server --edge-id your-edge-id --nats nats://localhost:4222

API Reference

Core Service Interface

The Service interface provides these methods:

• RegisterMCPServer: Add a new MCP server to the registry
• UnregisterMCPServer: Remove an MCP server from the registry
• ListTools: Get all available tools from registered servers
• SearchTools: Search for tools using semantic queries
• Forward: Route MCP requests to appropriate backend servers
• Close: Gracefully shutdown the service

HTTP API Endpoints

When HTTP transport is enabled:

# RESTful API
POST   /api/mcp/register           # Register MCP server
DELETE /api/mcp/unregister/:id     # Unregister MCP server
GET    /api/mcp/tools              # List all tools
GET    /api/mcp/tools/search       # Search tools
POST   /api/mcp/forward            # Forward tool calls

# MCP Protocol
POST   /mcp/                       # MCP JSON-RPC endpoint

Example Tool Search

// Semantic search for tools
tools, err := service.SearchTools(ctx, "what's the current time?", 5)
if err != nil {
    return err
}

for _, tool := range tools {
    fmt.Printf("Tool: %s - %s\n", tool.Name, tool.Description)
}

Example Tool Call

req := mcp.CallToolRequest{
    Request: mcp.Request{Method: "tools/call"},
    Params: mcp.CallToolParams{
        Name: "get_current_time",
        Arguments: map[string]any{
            "timezone": "Asia/Taipei",
        },
    },
}

result, err := service.Forward(ctx, req)
if err != nil {
    return err
}

// Handle result
if !result.IsError {
    for _, content := range result.Content {
        fmt.Printf("Result: %v\n", content)
    }
}

Transport Architecture

[MCP Clients] 
    ↓ (stdio/nats/http)
[MCPBlade Proxy/Service]
    ↓ (stdio/sse/streamable-http)  
[Backend MCP Servers]

Flow Description

1. Inbound: Clients connect to MCPBlade via:

   • stdio: Native MCP protocol (via mcpblade_mcp_server)
   • nats: Distributed messaging (via transport/nats/)
   • http: RESTful API and MCP streaming (via transport/http/)

2. Processing: MCPBlade aggregates, searches, and routes requests using:

   • Tool caching and deduplication
   • Vector-based semantic search
   • Health monitoring and heartbeat tracking

3. Outbound: MCPBlade connects to backend servers as an MCP client via:

   • stdio: Subprocess communication
   • sse: Server-Sent Events
   • streamable-http: HTTP streaming

Vector Search

Tools are automatically indexed in a vector database for intelligent search:

// Search finds tools using semantic similarity
tools, err := service.SearchTools(ctx, "time and date functions", 10)

// Tools are indexed with metadata including:
// - Server ID
// - Tool name and description
// - Input schema
// - Full tool JSON for reconstruction

The vector implementation uses ChromeDB with support for:

• In-memory collections for development
• Persistent storage for production
• Automatic embedding generation
• Similarity search with configurable result limits

Health Monitoring

The service continuously monitors the health of all registered MCP servers:

• Periodic Health Checks: Configurable TTL-based monitoring
• Heartbeat Tracking: Atomic timestamp tracking for each server
• Automatic Recovery: Failed servers can be automatically restarted
• Cache Refresh: Tool cache is refreshed based on health status
• Graceful Degradation: Failed servers are excluded from routing

Middleware System

MCPBlade uses a middleware architecture for cross-cutting concerns:

Logging Middleware

svc = mcpblade.LoggingMiddleware(logger)(svc)

Provides structured logging with Zap for all service operations.

Proxy Middleware

svc = mcpblade.ProxyMiddleware(endpoints)(svc)

Enables distributed deployments by proxying calls through NATS endpoints.

Development

Running Tests

# Run all tests
go test ./...

# Run with race detection
go test -race ./...

# Run specific test suite
go test ./service_test.go

Project Structure

├── cmd/
│   ├── mcpblade/                    # Main service executable
│   └── mcpblade_mcp_server/         # MCP server implementation
├── transport/
│   ├── nats/                        # NATS transport layer
│   │   ├── transport.go             # NATS handlers
│   │   ├── factory.go               # NATS client endpoints
│   │   └── topic.go                 # NATS topic routing
│   └── http/                        # HTTP transport layer
│       ├── transport.go             # HTTP handlers
│       ├── mcp.go                   # MCP streaming endpoints
│       └── router.go                # Route configuration
├── persistence/chromem/             # ChromeDB vector database
├── vector/                          # Vector database interfaces
├── mcp/                            # MCP protocol handlers
│   ├── endpoint.go                  # MCP endpoint implementations
│   └── endpoint_test.go             # MCP protocol tests
├── service.go                       # Core service implementation
├── service_test.go                  # Service integration tests
├── model.go                         # Data models and types
├── model_test.go                    # Model serialization tests
├── endpoint.go                      # Go-kit endpoints
├── proxy.go                         # Proxy middleware
├── logging.go                       # Logging middleware
└── config.example.yaml              # Example configuration

Dependencies

• mcp-go: MCP protocol implementation
• chromem-go: Vector database
• nats.go: NATS messaging with microservices
• go-kit: Microservice toolkit for endpoints
• gin: HTTP web framework
• zap: Structured logging
• cli/v3: Command-line interface

License

MIT License - see LICENSE.md for details.

This project is part of the FlareX ecosystem.

Contributing

Contributions are welcome! Please ensure:

1. All tests pass: go test ./...
2. Code follows Go conventions
3. New features include tests
4. Documentation is updated
5. Commit messages are descriptive

For major changes, please open an issue first to discuss the proposed changes.