wanaku-ai/wanaku

CategoryGeneral
AuthorCommunity
Stars4
PricingFree

Overview

Wanaku is an SSE-based MCP router designed to bridge the gap between AI agents and fragmented enterprise backend systems. Unlike standard single-purpose MCP servers, Wanaku acts as a routing layer, allowing developers to consolidate multiple internal APIs and data sources into a single entry point for LLMs. This architecture simplifies agent integration by decoupling the model's tool-calling interface from the underlying infrastructure. It is particularly useful for teams managing complex microservices or legacy systems that need to be exposed to AI agents without rewriting every endpoint into a separate MCP server. By leveraging Server-Sent Events (SSE), it ensures scalable, real-time communication between the agent and the enterprise ecosystem.

Highlights

  • SSE-based routing for scalable enterprise system integration
  • Consolidates multiple backend APIs into one MCP interface
  • Decouples AI tool-calling from underlying infrastructure
  • Extensible engine for custom enterprise routing logic
  • Simplifies agent connectivity across distributed microservices

Full Documentation

Wanaku - An MCP Router that connects everything

![License](LICENSE)
![Build](https://github.com/wanaku-ai/wanaku/actions)
![Release](https://github.com/wanaku-ai/wanaku/releases)

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:

bash
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

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

To preload forwards, mount a wanaku.yaml:

bash
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).

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

yaml
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):

bash
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):

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

  • Configuration - Environment variables and configuration reference

Community

  • Examples - Example capabilities and integrations

Related Projects

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

View official source
Join our Telegram