federating-mcp-servers

Federating fleet-owned MCP servers

Spring AI 1.1 ships spring-ai-starter-mcp-server-{webmvc,webflux,servlet}, so any Spring Boot service in the fleet can expose @Tool-annotated beans (and selected actuator endpoints) as MCP tools. When that happens, the right move is not to re-implement those tools inside spring-fleet — it is to federate them: register each service's MCP server alongside the spring-fleet MCP server so Claude sees one unified tool surface across the whole fleet.

When to use

/fleet-init records services[].stack.springAiMcpServer = true for any repo whose build declares spring-ai-starter-mcp-server. That flag is your signal.

Procedure

1. Discover the candidates. Iterate services[] and collect every one with stack.springAiMcpServer == true. For each, you need:

   • the transport URL (Streamable HTTP is the recommended 2026 transport; SSE is being sunset). The default Spring AI MCP server endpoint is http://<host>:<port><contextPath>/mcp. Confirm from each service's application.properties if spring.ai.mcp.server.base-path is set.
   • any required auth header (often a bearer token from the team's IDP).

2. Register them in the user's MCP client config. Claude Code reads .mcp.json. Append one entry per federated server next to the existing spring-fleet entry, e.g.:

   {
     "mcpServers": {
       "spring-fleet":      { "command": "python", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/mcp_server.py"] },
       "fleet-inventory":   { "transport": "streamable-http", "url": "http://localhost:8083/inventory-v1/mcp" },
       "fleet-order":       { "transport": "streamable-http", "url": "http://localhost:8081/order-v1/mcp" }
     }
   }
   

   Always prefix the federated server name with fleet- so the namespace is readable and collisions with non-fleet MCP servers are unlikely.

3. Confirm with the user before editing .mcp.json. Federation changes the agent's effective tool surface and the data it can read — that's a shared-state change worth a quick confirmation. Show the proposed diff.