Wanaku

Appearance

Frequently Asked Questions (FAQ) ​

General Questions ​

What is Wanaku? ​

Wanaku is an MCP (Model Context Protocol) Router that acts as a centralized hub for managing and governing how AI agents access tools and resources. It doesn't host tools or resources directly but instead routes requests to specialized capability services, providing unified access, security, and resource management for AI-enabled applications.

What does "Wanaku" mean? ​

The project name comes from the origins of the word "Guanaco," a camelid native to South America. The connection to Apache Camel (the integration framework used by Wanaku) makes this name particularly fitting.

What is the Model Context Protocol (MCP)? ​

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It defines how tools, resources, and prompts are exposed and accessed by AI agents. Learn more at modelcontextprotocol.io.

Is Wanaku open source? ​

Yes, Wanaku is open source and licensed under Apache 2.0. You can find the source code at github.com/wanaku-ai/wanaku.

What's the difference between tools and resources in Wanaku? ​

  • Tools operate in a request/reply mode, performing processing on input (e.g., making HTTP requests, executing commands, querying databases)
  • Resources provide read access to data without necessarily processing input (e.g., reading files, accessing S3 objects, reading Kafka topics)

Architecture and Design ​

Why does Wanaku use a router architecture instead of hosting tools directly? ​

The router architecture provides several advantages:

  • Isolation: Each capability service runs independently, improving security and reliability
  • Scalability: Services can be scaled independently based on demand
  • Flexibility: Easy to add, remove, or update capabilities without affecting the router
  • Language independence: Capability services can be written in any language that supports gRPC

What is a "capability" in Wanaku? ​

A capability is a service that provides specific functionality to the Wanaku router. Capabilities can be:

  • Tool services: Provide executable tools (HTTP client, exec, Tavily search, etc.)
  • Resource providers: Provide read access to resources (files, S3, FTP, etc.)
  • MCP servers: Bridge to other MCP servers via HTTP

How does Wanaku communicate with capability services? ​

Wanaku uses gRPC for communication between the router backend and capability services. This provides efficient, type-safe communication with built-in support for streaming and bidirectional communication.

What is the role of Keycloak in Wanaku? ​

Keycloak provides authentication and authorization for:

  • Router management API and web UI access
  • Service-to-service authentication between the router and capabilities
  • Future support for fine-grained access control to tools and resources

Installation and Setup ​

What are the prerequisites for running Wanaku? ​

For development:

  • Java 21 or later
  • Maven 3.x
  • Keycloak instance (optional — can run via Podman/Docker, or set wanaku.http.auth=none)

For production deployment:

  • OpenShift or Kubernetes cluster (optional but recommended)
  • Keycloak instance (recommended for production; optional with wanaku.http.auth=none)
  • Container runtime (Podman/Docker)

Do I need to install Keycloak separately? ​

Keycloak is required only if you want to run Wanaku with authentication enabled. You can:

  • Run Keycloak locally using Podman/Docker (for development)
  • Deploy Keycloak to OpenShift/Kubernetes (for production)
  • Use an existing Keycloak instance

If you don't need authentication (e.g., for local development or testing), you can set wanaku.http.auth=none and skip the Keycloak setup entirely. See Running Without Authentication.

Can I run Wanaku without Kubernetes? ​

Yes, Wanaku can run standalone on any machine with Java. You can:

  • Download pre-built binaries from the releases page
  • Build from source
  • Run locally for development and testing

Kubernetes/OpenShift deployment is recommended for production but not required.

How do I install the Wanaku CLI? ​

See the Installing the CLI section in the usage guide for all installation methods and PATH configuration.

Usage and Configuration ​

How do I add a new tool to Wanaku? ​

shell
# First ensure the capability service providing the tool is running
wanaku capabilities list

# Then add the tool
wanaku tools add --uri <tool-uri> --service <service-name>

See the Usage Guide for detailed instructions.

How do I add a new resource? ​

shell
# Ensure the resource provider service is running
wanaku capabilities list

# Add the resource
wanaku resources add --uri <resource-uri> --service <service-name>

What are namespaces and when should I use them? ​

Namespaces allow you to organize tools and resources into isolated groups. Use cases include:

  • Separating tools by environment (dev, staging, prod)
  • Organizing by team or project
  • Isolating tools by security level
  • Providing different tool sets to different AI agents

Wanaku provides 10 namespaces (ns-1 through ns-10) plus a default namespace and a public one.

How do I connect an MCP client to Wanaku? ​

For SSE transport:

text
http://localhost:8080/mcp/sse

For Streamable HTTP:

text
http://localhost:8080/mcp/

For a specific namespace:

text
http://localhost:8080/ns-1/mcp/sse

See Supported/Tested Clients for client-specific configuration.

Can I use Wanaku with Claude Desktop? ​

Yes, Wanaku works with Claude Desktop and other MCP-compatible clients. See the Usage Guide for configuration examples.

Development and Extension ​

How do I create a custom capability? ​

Use the Wanaku CLI to generate a project template:

For a tool service:

shell
wanaku services create tool --name my-tool

For a resource provider:

shell
wanaku services create provider --name my-provider

See the Contributing Guide for detailed instructions.

Should I use Camel or plain Quarkus for my capability? ​

Use the Camel Integration Capability (recommended for most cases):

  • When you need to integrate with external systems
  • To leverage 300+ Apache Camel components
  • For rapid development of common integration patterns

Use plain Quarkus when:

  • You need very specific custom logic
  • You want minimal dependencies
  • Performance is critical and you want full control

Can I write capability services in languages other than Java? ​

Yes! Any language that supports gRPC can be used to create capability services. The service must implement the appropriate gRPC protocol defined in the Wanaku core-exchange module.

Where should I put my custom capabilities? ​

Custom capabilities should generally go in the Wanaku Examples repository, not in the main Wanaku project. The main project is reserved for core, widely-applicable capabilities.

Security ​

Is Wanaku secure for production use? ​

Wanaku provides security features including:

  • OIDC-based authentication via Keycloak
  • Service-to-service authentication
  • TLS support for external endpoints
  • Network isolation via Kubernetes

However, you must properly configure these features. See the Security Guide for best practices.

How do I secure API keys and secrets used by tools? ​

Use the provisioning system to securely provide secrets to capability services:

  • Store secrets in Kubernetes Secrets
  • Configure tools to reference secrets via environment variables
  • Never commit secrets to version control

Does Wanaku support fine-grained access control? ​

Currently, all authenticated users have admin access to tools and resources. Fine-grained access control is planned for future versions.

Can I disable authentication for development? ​

While not recommended for production, you can set wanaku.http.auth=none to disable authentication for development and testing.

How to skip certificate validation for development purposes ​

  • Wanaku CLI: you can set the --insecure parameter to trust the server certificates.
  • Wanaku MCP server: set the environment variable QUARKUS_TLS_TRUST_ALL=true.

Troubleshooting ​

Why aren't my capability services showing up? ​

Common causes:

  1. Service registration is not enabled or misconfigured
  2. Network connectivity issues between service and router
  3. Incorrect OIDC credentials
  4. Service is not running or is crashing

See the Troubleshooting Guide for detailed solutions.

Why can't my MCP client connect to Wanaku? ​

Check:

  1. Router is running and accessible
  2. Correct endpoint URL (include /sse for SSE transport)
  3. Firewall rules allow traffic
  4. CORS is properly configured (for web clients)

How do I enable debug logging? ​

Add to application.properties:

properties
quarkus.log.level=DEBUG
quarkus.log.category."ai.wanaku".level=DEBUG
quarkus.mcp.server.traffic-logging.enabled=true

When using the Wanaku CLI, set the --verbose parameter to show additional logging.

Where can I get help? ​

Performance and Scaling ​

What are the resource requirements for Wanaku? ​

Minimum for development:

  • Router backend: 512MB RAM, 1 CPU
  • Each capability service: 256MB RAM, 0.5 CPU
  • Keycloak: 512MB RAM, 1 CPU

Recommended for production:

  • Router backend: 1-2GB RAM, 2 CPU
  • Capability services: 512MB-1GB RAM per service
  • Adequate resources for Keycloak

Can Wanaku handle multiple concurrent requests? ​

Yes, Wanaku is built on Quarkus and designed for concurrent request handling. Performance depends on:

  • Available system resources
  • Number and type of capability services
  • Network latency between components

Can I scale Wanaku horizontally? ​

The router backend can be scaled horizontally in Kubernetes. Capability services can also be scaled independently based on demand.

Compatibility ​

Which MCP clients are supported? ​

Any MCP client compliant with the MCP protocol is supported.

Wanaku was tested with different agents frameworks and MCP clients that include:

  • Claude Desktop
  • Langflow
  • LangChain4j MCP client
  • HyperChat
  • LibreChat
  • Witsy
  • Embedded LLMChat
  • And many others

Any MCP-compliant client should work with Wanaku.

What MCP protocol versions does Wanaku support? ​

Wanaku supports the current stable MCP protocol specification. Check the releases page for version compatibility information.

Can Wanaku act as a bridge to other MCP servers? ​

Yes! Wanaku includes an MCP-to-MCP bridge feature that allows it to forward requests to other MCP servers using HTTP transport, effectively aggregating multiple MCP servers behind a single endpoint.

Miscellaneous ​

What's the difference between Wanaku and running MCP servers directly? ​

Benefits of using Wanaku:

  • Centralized management and governance
  • Unified authentication and authorization
  • Tool and resource organization via namespaces
  • Service discovery and health monitoring
  • Ability to aggregate multiple MCP servers
  • Consistent interface regardless of backend services

Is there a web UI for Wanaku? ​

Yes, Wanaku includes a React-based web UI for managing the router, accessible by default at http://localhost:8080. However, some features are currently only available via the CLI.

How often is Wanaku updated? ​

Check the releases page for the latest versions and release notes. The project follows semantic versioning.

How can I contribute to Wanaku? ​

See the Contributing Guide for information on:

  • Setting up your development environment
  • Creating new capabilities
  • Submitting pull requests
  • Reporting issues

Where can I find examples and tutorials? ​