Wanaku - An MCP Router that connects everything

The Wanaku MCP Router is a router for AI-enabled applications powered by the Model Context Protocol (MCP). It sits between AI clients and your backend services, routing requests through a filter pipeline to provide namespace isolation, tool management, and MCP-to-MCP tool forwarding.

The project name comes from the origins of the word Guanaco, a camelid native to South America.

Key Features

• Unified MCP Routing - Centralized routing and resource management for AI agents
• MCP-to-MCP Bridge - Act as a gateway or proxy for other MCP servers, with auto-discovery of remote tools
• Multi-Namespace Support - Organize tools and resources across isolated namespaces
• Secure by Default - Authentication and authorization via oauth2-proxy and Keycloak (optional — can run without auth)
• Extensible Architecture - Plugin system via feature crates and a composable filter pipeline
• Admin Dashboard - Web UI for managing tools, resources, prompts, and forwards
• Container-Ready - Multi-arch images (x86_64, aarch64) published automatically

Quick Start

Install

Download the latest early-access build on Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/wanaku-ai/wanaku/main/get-wanaku-praxis.sh | bash

The installer detects the host platform, verifies the release checksum, and installs wanaku-praxis into $HOME/bin. Override the destination with WANAKU_PRAXIS_INSTALL_DIR.

Container

podman run -p 8080:8080 -p 8081:8081 quay.io/wanaku/wanaku-praxis

To preload forwards, mount a wanaku.yaml:

podman run -p 8080:8080 -p 8081:8081 \
  -v ./wanaku.yaml:/etc/wanaku-praxis/wanaku.yaml \
  quay.io/wanaku/wanaku-praxis \
  --wanaku-config /etc/wanaku-praxis/wanaku.yaml

From Source

Note

Building from source requires: Rust 1.96+ and Yarn (for the admin UI).

cargo build
cargo run

The first cargo build automatically builds the admin UI via yarn if ui/admin/dist/ is missing.

Endpoints

Endpoint	Address	Description
MCP	http://localhost:8081/mcp	MCP protocol endpoint (or /{namespace}/mcp for namespaced access)
Management API	http://localhost:8080/api/v1/...	CRUD for tools, resources, prompts, forwards, namespaces
Admin UI	http://localhost:8080/admin/	Web dashboard

Learn Wanaku

The easiest way to learn Wanaku is by following the guided tutorial.

The reference documentation, including the complete installation and configuration instructions, is available in the usage guide.

Configuration

Drop a wanaku.yaml in the working directory to preload forward definitions:

forwards:
  - name: "upstream-mcp"
    address: "http://remote.example.com/mcp"

If no config file is provided, the server starts with an empty registry that can be populated via the management API.

Management API Examples

Register a remote MCP server as a forward (its tools are auto-discovered):

curl -X POST http://localhost:8080/api/v1/forwards \
  -H "Content-Type: application/json" \
  -d '{
    "name": "upstream-mcp",
    "address": "http://remote.example.com/mcp"
  }'

Refresh tools from the forward (auto-discover):

curl -X POST http://localhost:8080/api/v1/forwards/upstream-mcp/refreshes

All tools from the remote server now appear in your local catalog. The client has no idea they're forwarded.

Authentication

Authentication is handled externally by oauth2-proxy. Two instances sit in front of the MCP and management ports, sharing an SSO cookie:

• MCP proxy (:4180 → :8081) — protects MCP endpoints, any authenticated user
• Management proxy (:4181 → :8080) — protects the admin UI and REST API, admin role required

Wanaku also serves RFC 9728 OAuth Protected Resource Metadata at /.well-known/oauth-protected-resource/{namespace}/mcp. Set WANAKU_AUTH_ISSUER to your Keycloak realm URL to populate the authorization_servers field.

See deploy/auth/README.md for setup instructions (Docker Compose and local development).

Documentation

The Wanaku Documentation website contains the full project documentation.

Contributors working on the project may want to refer to the development documentation:

• Getting Started - Development setup guide
• Architecture - System architecture and components
• Configuration - Environment variables and configuration reference
• Management API - API reference
• Admin UI - Admin dashboard development
• Features / Plugins - Feature crate system
• Plugin Development - Guide for writing new feature crates
• Evaluator Engine - WASM-based evaluator
• Contributing - Contribution guidelines
• Security - Security policy

Community

• GitHub Issues - Bug reports and feature requests
• Discussions - Ask questions and share ideas
• Examples - Example capabilities and integrations

Related Projects

• Camel Integration Capability - Apache Camel-based capability services
• Java SDK - SDK for building capability services in Java

License

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