Wanaku MCP Router: Getting Started on Your Laptop

Run a local Wanaku router, import an HTTP toolset, forward an upstream MCP server, and merge both into one agent catalog.

Jul 08, 2026

Agent demos are easy to fake. Add one clean endpoint, wire one happy-path tool, and the screenshot looks finished. The hard part starts when the agent needs to talk to systems you already have. One HTTP API here. One file tree there. Maybe an MCP server another team already runs and nobody wants to rewrite just because an LLM showed up.

That is the problem Wanaku is trying to solve.

Wanaku is an open-source MCP router built on Quarkus and Apache Camel. Your agent connects to one Wanaku endpoint over the Model Context Protocol, and Wanaku manages the catalog behind it: tools and forwards to other MCP servers. That gives you one place to manage what the agent can see instead of hand-wiring every capability into every client.

I wanted to try Wanaku since a while and had this on my to-do list. Finally got a chance to run an example and share what I learned. From idea to this tutorial, a few parts did not survive contact with the real CLI. The working path below uses a local Wanaku router, one imported HTTP toolset, and one forwarded upstream MCP server.

What We Are Building

A local Wanaku router on http://localhost:8080
One imported HTTP toolset from the official wanaku-toolsets repository
One forwarded upstream MCP server: the official Everything reference server from the MCP servers repository
A verified catalog that shows local HTTP tools and remote MCP tools behind the same router

This is not the exact bridge I wanted to use. I started with the official filesystem server because that looks closer to real work. In Wanaku 0.1.3, that path failed for reasons I explain later. The bridge below is the one that worked end to end.

What You Need

Java 21 or later
A recent Node.js with npx
Internet access on first run, because Wanaku and the MCP server packages need to be downloaded (obvl)
☕️☕️☕️

I recommend Java 21 for this article. In my validation run, Wanaku 0.1.3 installed on Java 25, but the CLI needed extra JVM flags because of module access rules.

Check the local runtime first:

java -version
node -v
npx --version

If you are already on Java 25 and want to stay there, I had to use this during validation:

export JAVA_TOOL_OPTIONS='--add-opens=java.base/java.lang=ALL-UNNAMED'

That is a workaround. I could not find official docs about Java version support with Wanaku yet.

Install the Wanaku CLI

For a Mac tutorial, the JBang path is the simplest one because it avoids hardcoding a release ZIP names.

Install JBang:

brew install jbangdev/tap/jbang
jbang version
jbang app setup

Open a new terminal, or reload your shell so the JBang app path is available. After that, install Wanaku:

jbang app install wanaku@wanaku-ai/wanaku
wanaku --version

If you want to run this on Java 25, use wanaku --help to check if it works. In my run, wanaku --version did not.

Start Wanaku Locally

Before starting the stack, ask Wanaku which local services it can launch:

wanaku start local --list-services

In my run, the local service catalog was:

service-http
service-tavily
service-exec

That list matters later because it explains why my file resource example did not work.

Now start the local router:

wanaku start local

Keep that terminal open. Local mode disables authentication automatically, which is fine for a laptop demo and wrong for anything shared.

After startup, check the router health:

curl -s http://127.0.0.1:8080/q/health
curl -s http://127.0.0.1:9000/q/health

In my validation run, both the router on 8080 and the HTTP capability service on 9000 reported UP.

Import a First Toolset

The fastest way to put a real tool behind Wanaku is to import a toolset. I used the official currency example and listed the catalog against the explicit host so the output is predictable:

wanaku tools import --plain --no-auth --host http://127.0.0.1:8080 \
  https://raw.githubusercontent.com/wanaku-ai/wanaku-toolsets/refs/heads/main/toolsets/currency.json

wanaku tools list --plain --no-auth --host http://127.0.0.1:8080

Look for free-currency-conversion-tool in the output.

That part worked cleanly.

Bridge Another MCP Server into Wanaku

The next step is the one I really wanted to test. I wanted a real external MCP server sitting behind Wanaku so the router was doing more than wrapping HTTP.

For the validated path, I used the official Everything reference server in native SSE mode:

npx -y @modelcontextprotocol/server-everything sse

Keep that terminal open too.

In my run, the server started on port 3001 and logged:

Starting SSE server...
Server is running on port 3001

Now we need a namespace ID for the forward. This is one of the rough edges in the current CLI: wanaku forwards add wants a namespace ID. The easiest reproducible way I found was to reuse one of the preallocated local namespaces.

Extract the ID behind the ns-1 path:

WANAKU_NAMESPACE_ID=$(
  wanaku namespaces list --plain --no-auth --host http://127.0.0.1:8080 \
    | awk '$2 ~ /ns-1\\/mcp\\/sse$/ {print $1; exit}'
)

printf '%s\n' "$WANAKU_NAMESPACE_ID"

Add the forward:

wanaku forwards add --plain --no-auth --host http://127.0.0.1:8080 \
  -N "$WANAKU_NAMESPACE_ID" \
  --service="http://127.0.0.1:3001/sse" \
  --name local-everything-sse

Then verify both the forward and the expanded tool catalog:

wanaku forwards list --plain --no-auth --host http://127.0.0.1:8080
wanaku tools list --plain --no-auth --host http://127.0.0.1:8080

In my run, wanaku forwards list showed:

name                 address
local-everything-sse http://127.0.0.1:3001/sse

And wanaku tools list showed the imported currency tool plus remote MCP tools such as:

echo
get-sum
get-env
get-tiny-image
trigger-long-running-operation
simulate-research-query

That is the fully working bridge: one Wanaku router, one local HTTP toolset, one external SSE MCP server, one merged catalog.

What This Proves

At this point, we have all up and running.

Wanaku starts locally and serves a healthy router endpoint
Wanaku imports a normal HTTP toolset cleanly
Wanaku connects to a separate MCP server over SSE
Wanaku imports remote MCP tools into its own catalog under a namespace

That is enough to show the routing model is real.

What Broke in My Run

Lessons learned so you don’t have to.

Filesystem Server Through Supergateway

I started with this bridge:

npx -y supergateway \
  --stdio "npx -y @modelcontextprotocol/server-filesystem $HOME/wanaku-demo" \
  --port 8001 \
  --baseUrl http://127.0.0.1:8001

That looks reasonable. It did not survive the live run.

What happened:

Wanaku connected to the upstream SSE endpoint
The filesystem server asked for roots/list
Wanaku replied with an empty roots list
The filesystem server exited with No valid root directories provided by client
On the next connection attempt, Supergateway crashed with Already connected to a transport

So this did not happen for this article.

Memory Server Through Supergateway

I also tried the official memory server behind Supergateway:

npx -y supergateway \
  --stdio "npx -y @modelcontextprotocol/server-memory" \
  --port 8002 \
  --baseUrl http://127.0.0.1:8002

That failed differently. Wanaku probed resources/list, the server replied with Method not found, and Wanaku treated the upstream as unavailable.

That tells me the current forward path is more demanding than “any MCP server behind an SSE bridge.” I have not looked into this deeper to figure out who’s fault this is. But maybe I find some time and find out more.

The Primitives, With the Current Rough Edges

The original idea I had for this article wanted to show tools and forwards as if they were equally smooth in local mode. They were not.

Tools

Tools are the cleanest part of the current local flow. The imported currency toolset worked immediately:

wanaku tools import --plain --no-auth --host http://127.0.0.1:8080 \
  https://raw.githubusercontent.com/wanaku-ai/wanaku-toolsets/refs/heads/main/toolsets/currency.json

If your backend already has an OpenAPI document, the next command to look at is:

wanaku tools generate http://petstore3.swagger.io/api/v3/openapi.yaml

That is where Wanaku stops looking like a demo wrapper and starts looking like a migration path.

Forwards

Forwards are the part that gives Wanaku real architectural value. They also have the sharpest edges right now.

The native SSE bridge to the Everything server worked:

wanaku forwards add --plain --no-auth --host http://127.0.0.1:8080 \
  -N "$WANAKU_NAMESPACE_ID" \
  --service="http://127.0.0.1:3001/sse" \
  --name local-everything-sse

The stdio-to-SSE bridges I tried were much less forgiving.

Why This Architecture Still Makes Sense

Even with the rough edges, the core idea still holds up.

Your agent does not need direct knowledge of every backend, every tool definition, every upstream MCP server, and every transport quirk. It needs one stable place to connect. Wanaku turns the rest into catalog management. Add a tool. Forward another MCP server. Keep the client side simpler.

The Apache Camel base matters too. Today the working example is an HTTP tool plus an upstream SSE MCP server. Tomorrow it can be a real Camel route, a Salesforce integration, or an internal API you already describe with OpenAPI. The routing model still makes sense even when a few local-mode features are rough.

What to Try Next

Stay on Java 21 for now unless you want to carry the Java 25 JVM workaround.
Start with an upstream server that already speaks SSE if you want the cleanest first forward.
Treat stdio-to-SSE bridges as something to validate case by case, especially when the upstream server depends on roots or does not implement resources/list.
Revisit file resources and prompt registration after Wanaku local mode exposes the right providers and the current prompt persistence error is fixed.

Discussion about this post

Ready for more?