Wanaku MCP Router Architecture

Overview

The Wanaku MCP Router is a distributed system for managing Model Context Protocol (MCP) workloads, providing a flexible and extensible framework for integrating AI agents with enterprise systems and tools.

Key Architectural Principles

• Separation of Concerns: Router backend handles protocol and routing; capability services handle actual operations
• Service Isolation: Each capability runs independently for security and reliability
• Protocol Abstraction: MCP protocol details are handled by the router; services focus on business logic
• Dynamic Discovery: Services register themselves at runtime, enabling flexible deployment

High-Level Architecture

Wanaku doesn't directly host tools or resources. Instead, it acts as a central hub that manages and governs how AI agents access specific resources and capabilities through registered services.

The router uses a bridge architecture with composition over inheritance to separate transport concerns from business logic, enabling flexible and testable implementations.

NOTE

For detailed information about the router's internal implementation, including the bridge pattern and transport abstraction, see Wanaku Router Internals.

System Components

graph TB
    subgraph "Client Layer"
        LLM[LLM Client<br/>Claude, HyperChat, etc.]
    end

    subgraph "Router Layer"
        Router[Router Backend<br/>MCP Server]
        CLI[CLI Tool]
        UI[Web UI]
        Persist[(Infinispan<br/>Persistence)]
        Auth[Keycloak<br/>Authentication]
    end

    subgraph "Capability Layer"
        TS1[Tool Service<br/>HTTP]
        TS2[Tool Service<br/>Exec]
        TS3[Tool Service<br/>Tavily]
        CIC1[Camel Integration<br/>Capability]
    end

    LLM -->|MCP Protocol| Router
    CLI -->|REST API| Router
    UI -->|REST API| Router
    Router -->|Auth| Auth
    Router -->|Persist| Persist
    Router -->|gRPC| TS1
    Router -->|gRPC| TS2
    Router -->|gRPC| TS3
    Router -->|gRPC| CIC1

    style Router fill:#4A90E2
    style LLM fill:#50C878
    style TS1 fill:#FFB347
    style TS2 fill:#FFB347
    style TS3 fill:#FFB347
    style CIC1 fill:#DDA0DD

Core Router Components

Router Backend (wanaku-router-backend)

The main MCP server engine that:

• Receives MCP protocol requests from AI clients (SSE and HTTP transports)
• Routes tool invocations to appropriate tool services via gRPC
• Routes resource read requests to appropriate providers via gRPC
• Manages tool and resource registrations across namespaces
• Provides HTTP management API for configuration
• Handles authentication and authorization via Keycloak

Technology Stack: Quarkus, Quarkus MCP Server Extension, gRPC, Infinispan

CLI (cli)

Command-line interface for router configuration and management:

• Tool and resource management
• Namespace configuration
• Capability service monitoring
• Project scaffolding for new capabilities
• OAuth 2.0/OIDC authentication

Web UI (ui)

React-based administration interface:

• Visual tool and resource management
• Capability service status monitoring
• Configuration management
• User authentication via Keycloak

Capability Services

Capability services extend the router's functionality by providing specific tools or resource access.

Tool Services

Tool services provide LLM-callable capabilities through the MCP protocol:

Service	Purpose	Technology
HTTP Tool Service	Make HTTP requests to REST APIs and web services	Apache Camel
Exec Tool Service	Execute system commands and processes	Native execution
Tavily Tool Service	Search integration through Tavily API	Tavily SDK

Resource Providers

Resource providers enable access to different data sources and storage systems.

Wanaku does not come with any resource provider out of the box, but you can find some in the Wanaku Examples repository.

Core Libraries

Shared libraries providing foundational functionality:

Library	Purpose
core-exchange	gRPC protocols and message exchange definitions
core-mcp	MCP protocol implementation and client libraries
wanaku-capabilities-base	Base classes for capability implementations (in capabilities-quarkus-sdk)
core-service-discovery	Service registration and health monitoring
core-persistence	Data persistence abstractions with Infinispan

Development Tools

Tool	Purpose
Archetypes	Maven archetypes for creating new capabilities
MCP Servers	Specialized MCP server implementations for bridging

Architecture Patterns

Distributed Microservices Architecture

Wanaku follows a distributed microservices architecture where the central router coordinates with independent provider and tool services:

• Router as Gateway: Central entry point for all MCP requests
• Service Independence: Each capability service runs as an independent process
• Protocol Translation: Router handles MCP protocol; services use gRPC
• Horizontal Scalability: Services can be scaled independently

Request Flow

sequenceDiagram
    participant Client as LLM Client
    participant Router as Router Backend
    participant Bridge as Bridge Layer
    participant Transport as Transport Layer
    participant Service as Capability Service
    participant Target as External System

    Client->>Router: MCP Request (Tool Call)
    Router->>Router: Authenticate Request
    Router->>Bridge: Route to Appropriate Bridge
    Bridge->>Bridge: Process Business Logic
    Bridge->>Transport: Delegate to Transport
    Transport->>Service: gRPC Tool Invocation
    Service->>Target: Execute Operation
    Target-->>Service: Operation Result
    Service-->>Transport: gRPC Response
    Transport-->>Bridge: Parsed Response
    Bridge-->>Router: Aggregated Result
    Router-->>Client: MCP Response

Flow Steps:

1. Client Connection: LLM client connects to router backend via MCP protocol (SSE or HTTP)
2. Authentication: Router authenticates the request using Keycloak/OIDC
3. Request Processing: Router receives MCP requests (tool calls, resource reads, prompt requests)
4. Bridge Routing: Bridge layer determines the appropriate service based on tool/resource type and namespace
5. Business Logic: Bridge processes request and prepares for transport asynchronously
6. Transport Delegation: Bridge delegates communication to transport layer (composition pattern)
7. gRPC Communication: Transport forwards request to specific capability service via gRPC and transforms the response using response transformers
8. Service Processing: Capability service handles actual resource access or tool execution
9. Async Response: Results are returned as Uni types through transport and bridge layers back to client

Tool Invocation Flow

sequenceDiagram
    participant LLM as LLM Agent
    participant Router as Router Backend
    participant Bridge as InvokerBridge
    participant Transport as GrpcTransport
    participant Registry as Service Registry
    participant ToolSvc as HTTP Tool Service
    participant API as External API

    LLM->>Router: Call Tool "http://api.example.com/data"
    Router->>Registry: Lookup Service for "http://" URI
    Registry-->>Router: Return HTTP Service Details
    Router->>Bridge: execute(arguments, reference)
    Bridge->>Transport: invokeTool(request, service)
    Transport->>ToolSvc: gRPC ToolInvoke(uri, params)
    ToolSvc->>API: HTTP GET /data
    API-->>ToolSvc: JSON Response
    ToolSvc-->>Transport: gRPC Response
    Transport-->>Bridge: Uni~ToolResponse~
    Bridge-->>Router: Uni~ToolResponse~
    Router-->>LLM: MCP Tool Result

Resource Read Flow

sequenceDiagram
    participant LLM as LLM Agent
    participant Router as Router Backend
    participant Bridge as ResourceAcquirerBridge
    participant Transport as GrpcTransport
    participant Registry as Service Registry
    participant FileProv as File Provider
    participant FS as File System

    LLM->>Router: Read Resource "file:///path/to/doc.txt"
    Router->>Registry: Lookup Provider for "file://" URI
    Registry-->>Router: Return File Provider Details
    Router->>Bridge: read(arguments, resource)
    Bridge->>Transport: acquireResource(request, service, ...)
    Transport->>FileProv: gRPC ReadResource(uri)
    FileProv->>FS: Read File
    FS-->>FileProv: File Contents
    FileProv-->>Transport: gRPC Response (contents)
    Transport-->>Bridge: Uni~List~ResourceContents~~
    Bridge-->>Router: Uni~ResourceResponse~
    Router-->>LLM: MCP Resource Content

Service Discovery and Registration

The router maintains a dynamic service registry that tracks available capability services.

sequenceDiagram
    participant Service as Capability Service
    participant Router as Router Backend
    participant Registry as Service Registry
    participant Health as Health Monitor

    Service->>Router: Register (name, URI, capabilities)
    Router->>Registry: Store Service Info
    Router-->>Service: Registration Confirmed

    loop Heartbeat (every 10s)
        Service->>Router: Heartbeat Ping
        Router->>Health: Update Health Status
        Router-->>Service: Pong
    end

    Note over Router,Health: If heartbeat missed<br/>mark service offline

    Router->>Registry: Query Available Services
    Registry-->>Router: Return Active Services

Registration Process:

1. Service Startup: Capability service starts and loads configuration
2. Authentication: Service authenticates with router using OIDC client credentials
3. Registration: Service registers itself with router, providing:
   • Service name and type
   • gRPC endpoint address
   • Supported capabilities (tool types or resource protocols)
   • Configuration schema
4. Health Monitoring: Service sends periodic heartbeats to indicate availability
5. Dynamic Discovery: Router updates service registry and makes capabilities available
6. Deregistration: Service deregisters on shutdown or is marked offline after missed heartbeats

Namespace Isolation

Namespaces provide logical isolation for organizing tools and resources:

• Default Namespace: Standard workspace for general-purpose tools and resources
• Custom Namespaces (ns-1 through ns-10): Isolated environments for specific use cases
• Public Namespace: Read-only access to shared tools and resources
• Isolation: Tools and resources in one namespace are not visible to clients connected to another

Security Architecture

graph TB
    subgraph "Authentication Layer"
        Keycloak[Keycloak<br/>Identity Provider]
    end

    subgraph "Router Layer"
        Router[Router Backend]
        Proxy[Proxy Layer]
    end

    subgraph "Capability Layer"
        Service1[Tool Service]
        Service2[Resource Provider]
    end

    Client[LLM Client] -->|1. Authenticate| Keycloak
    Keycloak -->|2. Token| Client
    Client -->|3. MCP Request + Token| Router
    Router -->|4. Validate Token| Keycloak
    Router -->|5. Authorized Request| Proxy

    Service1 -->|A. Register + OIDC| Router
    Service2 -->|B. Register + OIDC| Router
    Proxy -->|6. gRPC + Service Auth| Service1
    Proxy -->|7. gRPC + Service Auth| Service2

    style Keycloak fill:#E74C3C
    style Router fill:#4A90E2
    style Service1 fill:#FFB347
    style Service2 fill:#DDA0DD

Security Layers:

1. Client Authentication: LLM clients authenticate via OIDC with Keycloak
2. Token Validation: Router validates access tokens for each request
3. Service-to-Service Auth: Capability services use client credentials to authenticate with router
4. RBAC (Future): Role-based access control for fine-grained permissions
5. Provisioning Security: Sensitive configuration delivered via encrypted channels

Data Persistence

graph LR
    subgraph "Router Backend"
        API[Management API]
        MCP[MCP Server]
    end

    subgraph "Persistence Layer"
        Infinispan[(Infinispan<br/>Data Grid)]
    end

    subgraph "Stored Data"
        Tools[Tool Definitions]
        Resources[Resource Definitions]
        Namespaces[Namespace Config]
        Services[Service Registry]
        History[State History]
    end

    API --> Infinispan
    MCP --> Infinispan
    Infinispan --> Tools
    Infinispan --> Resources
    Infinispan --> Namespaces
    Infinispan --> Services
    Infinispan --> History

    style Infinispan fill:#4A90E2

Wanaku uses Infinispan embedded data grid for persistence:

• Tool Definitions: Registered tools with URIs, labels, and configuration
• Resource Definitions: Registered resources with URIs and metadata
• Namespace Configuration: Namespace settings and mappings
• Service Registry: Active capability services and their health status
• State History: Historical snapshots for rollback and auditing (configurable retention)

Extensibility Model

New capabilities can be added through multiple approaches:

1. Tool Services

graph LR
    Dev[Developer] -->|1. Generate| Archetype[Maven Archetype]
    Archetype -->|2. Create| Project[Tool Service Project]
    Project -->|3. Implement| Logic[Business Logic]
    Logic -->|4. Build| Service[Tool Service]
    Service -->|5. Deploy| Runtime[Runtime Environment]
    Runtime -->|6. Register| Router[Router Backend]

    style Archetype fill:#FFB347
    style Service fill:#50C878
    style Router fill:#4A90E2

Steps:

1. Use wanaku services create tool --name my-tool to generate project
2. Implement tool logic using Java/Camel or other gRPC-capable language
3. Configure service registration and OIDC credentials
4. Deploy service (standalone or containerized)
5. Service auto-registers with router on startup

2. Resource Providers

Similar pattern to tool services, using wanaku services create provider

3. MCP Server Bridging

graph LR
    External[External MCP Server] -->|HTTP| Bridge[MCP Bridge Service]
    Bridge -->|gRPC| Router[Router Backend]
    Router -->|MCP| Client[LLM Client]

    style External fill:#E74C3C
    style Bridge fill:#FFB347
    style Router fill:#4A90E2
    style Client fill:#50C878

Wanaku can aggregate external MCP servers, presenting them as unified capabilities.

4. Apache Camel Integration

Leverage 300+ Camel components for rapid integration:

• Kafka, RabbitMQ, ActiveMQ
• AWS, Azure, Google Cloud services
• Databases (SQL, MongoDB, etc.)
• Enterprise systems (SAP, Salesforce, etc.)

Design Decisions

Why gRPC for Internal Communication?

• Performance: Binary protocol with efficient serialization
• Type Safety: Strongly-typed contracts via Protocol Buffers
• Streaming: Built-in support for bidirectional streaming
• Language Agnostic: Capability services can be written in any language

Why Separate Router and Capability Services?

• Isolation: Failures in one capability don't affect others
• Independent Scaling: Scale services based on demand
• Technology Flexibility: Use different tech stacks per service
• Security: Contain potential vulnerabilities to specific services

Why Bridge Pattern with Composition?

• Separation of Concerns: Business logic separated from transport implementation
• Testability: Easy to mock transport layer for unit testing
• Flexibility: Support multiple transport protocols (gRPC, HTTP, WebSocket)
• Maintainability: Changes to transport don't affect business logic
• Extensibility: New transport implementations without modifying bridges

Why Infinispan for Persistence?

• Embedded: No external database dependency for simple deployments
• Performance: In-memory data grid with fast access
• Clustering: Supports distributed deployments (future)
• ACID: Transactional consistency for critical operations

Deployment Architectures

Local Development

graph TB
    subgraph "Local Machine"
        KC[Keycloak<br/>Port 8543]
        Router[Router Backend<br/>Port 8080]
        Service1[HTTP Tool<br/>Port 9009]
        Service2[File Provider<br/>Port 9010]
        CLI[CLI Tool]
    end

    Client[LLM Client] -->|MCP| Router
    CLI -->|API| Router
    Router -->|Auth| KC
    Router -->|gRPC| Service1
    Router -->|gRPC| Service2

    style Router fill:#4A90E2
    style KC fill:#E74C3C

Characteristics:

• All components run on localhost
• Simple podman/docker setup for Keycloak
• Easy debugging and development
• No network complexity

Kubernetes/OpenShift Deployment

graph TB
    subgraph "Kubernetes Cluster"
        subgraph "Namespace: wanaku-system"
            KC[Keycloak<br/>Service]
            Router[Router Backend<br/>Deployment]
            UI[Web UI<br/>Deployment]
        end

        subgraph "Namespace: wanaku-capabilities"
            TS1[HTTP Tool<br/>Deployment]
            TS2[Exec Tool<br/>Deployment]
            RP1[File Provider<br/>Deployment]
            RP2[S3 Provider<br/>Deployment]
        end

        Ingress[Ingress Controller]
    end

    External[External Clients] -->|HTTPS| Ingress
    Ingress --> Router
    Ingress --> UI
    Router -->|Internal DNS| KC
    Router -->|gRPC| TS1
    Router -->|gRPC| TS2
    Router -->|gRPC| RP1
    Router -->|gRPC| RP2

    style Router fill:#4A90E2
    style KC fill:#E74C3C
    style Ingress fill:#95A5A6

Characteristics:

• Production-grade deployment
• Service discovery via Kubernetes DNS
• Horizontal pod autoscaling
• ConfigMaps and Secrets for configuration
• Health checks and rolling updates

Performance Considerations

Throughput

• MCP Requests: Router handles concurrent requests asynchronously using Mutiny Uni types
• gRPC: Efficient binary protocol with FutureStub-based async invocations reduces serialization overhead
• Connection Caching: gRPC channels are cached and reused per service target
• Async Processing: Non-blocking I/O throughout the stack with response transformation at the transport layer

Latency

Typical request latency breakdown:

Component	Latency	Notes
MCP Protocol Overhead	~5ms	SSE/HTTP serialization
Router Processing	~10ms	Routing, auth validation
gRPC Communication	~2ms	Internal network
Capability Processing	Variable	Depends on operation
Total (excluding operation)	~17ms	Overhead without actual work

Scaling Strategies

1. Vertical Scaling: Increase router resources for higher throughput
2. Horizontal Scaling: Multiple router instances behind load balancer (future)
3. Capability Scaling: Scale individual services based on demand
4. Caching: Infinispan caching reduces repeated lookups

Related Documentation

• Wanaku Router Internals - Deep dive into proxy architecture and implementation
• Configuration Guide - Complete configuration reference
• Contributing Guide - How to extend Wanaku with new capabilities
• Security Guide - Security best practices and policies
• Usage Guide - Operational guide for using Wanaku