Nexus (Spring AI 1.1.0-M3)

A fan‑in MCP Gateway using Spring Boot 3.5.x and Spring AI 1.1.0‑M3:

• Front door: Streamable‑HTTP MCP Server (looks like a normal MCP server to clients).
• Back ends: Placeholder registry that you can wire to stdio / SSE / Streamable‑HTTP / Stateless‑HTTP MCP servers via Spring AI MCP Client Boot Starter.
• MVP tool: nexus/route — lets you invoke any downstream tool by serverId and tool name. Ships with an echo demo backend so you can test immediately.

🔧 TODO: Set gateway.mount.enabled=true to have the NexusMount component enumerate downstream catalogs in the logs. Dynamic ToolCallback registration for a real union mount will be completed once Spring AI MCP clients are wired in.

Quick start

1. Copy the secrets template and add your tokens:

   cp vars.yaml.template vars.yaml

   Fill in vars.yaml with GITHUB_PERSONAL_ACCESS_TOKEN if you plan to call the GitHub backend.
2. Start the gateway:

   ./run.sh --local        # loads vars.yaml then bootstraps Spring Boot

   Alternatively, export the variables yourself and run ./mvnw spring-boot:run.

Connect your MCP client (Cursor/Claude) to the gateway's Streamable‑HTTP endpoint (default http://localhost:8080).

Tools exposed

• nexus/ping — health check (local tool)
• nexus/route — generic router:
  • Input:

    { "serverId": "echo", "tool": "echo", "args": { "message": "hi" } }

  • Output: pass‑through of downstream result (streams/logging included when available)

The project starts with a demo backend (echo) so you can try nexus/route right away. Other backends listed in application.yml return a "transport not implemented" response until you provide real Spring AI MCP clients.

Wiring real backends

1. Define backends in application.yml under gateway.backends (id, transport, url, headers).
2. Implement adapters in DownstreamRegistry that build actual Spring AI MCP clients (stdio/SSE/streamable/stateless) instead of the placeholder UnsupportedClient.
3. Flip gateway.mount.enabled=true to see the downstream catalog emitted in logs. Replace the TODO in NexusMount when you are ready to register namespaced tools, e.g., git/commit.
4. (Optional) Use ./run.sh --cf to package and push the app to Cloud Foundry with the vars file.

See the Spring AI docs you shared for the precise client/server beans and configuration keys:

• MCP overview and transports
• MCP client/server boot starters
• Streamable HTTP server
• MCP security
• MCP annotations

Security

SecurityConfig currently permits all exchanges. Add your preferred API-key/JWT/RBAC setup there before exposing the gateway publicly.

Observability

Micrometer/OTel deps are included; export to your collector via standard Spring Boot config.

---

Note: This repo is intentionally scaffolded to compile cleanly without hard binds to internal Spring AI client types. Fill the TODOs once you decide which transports you’ll use.