Spring Boot MCP Server in 2026: The Transport Trap That Wastes Your Weekend

A developer built a Spring Boot MCP server that exposes database queries, REST API calls, and file system access as tools for AI agents like Claude, GitHub Copilot, and Cursor. The project highlights a common transport trap where using the wrong Maven starter (stdio vs. SSE) causes silent failures with no error messages. The fix is a single configuration line matching the starter to the client type.

I spent an afternoon staring at "connection refused" on my first MCP server. The fix was one config line. Here's what no README tells you upfront. Model Context Protocol is the standard that lets AI agents — Claude, GitHub Copilot, Cursor — call your code as a tool. Instead of the AI just generating text, it can actually invoke your functions and get real data back. Think of it as giving Claude a set of keys to specific doors in your Java backend. It asks "can you run this query?" — your MCP server runs it, returns the result — Claude uses that result in its response. For Java teams, this is significant. There are millions of Spring Boot services sitting in production right now that AI agents can't touch. MCP changes that. Here's the full working server — a Spring Boot MCP server that exposes database queries, REST API calls, and file system access as tools any AI agent can call. Maven dependencies: <dependency <groupId org.springframework.ai</groupId <artifactId spring-ai-starter-mcp-server-webmvc</artifactId </dependency <dependencyManagement <dependencies <dependency <groupId org.springframework.ai</groupId <artifactId spring-ai-bom</artifactId <version 1.0.0</version <type pom</type <scope import</scope </dependency </dependencies </dependencyManagement Your first tool: @Service public class DatabaseMcpTools { @Autowired private JdbcTemplate jdbc; @Tool description = "Run a read-only SQL query on the application database" public String queryDatabase @ToolParam description = "SQL SELECT query to execute" String sql { if sql.trim .toUpperCase .startsWith "SELECT" { return "Error: only SELECT queries are permitted"; } return jdbc.queryForList sql .toString ; } @Tool description = "List all tables in the database schema" public String listTables { return jdbc.queryForList "SELECT table name FROM information schema.tables " + "WHERE table schema = 'public'" .toString ; } } application.yml : spring: ai: mcp: server: name: my-mcp-server version: 1.0.0 instructions: "Provides database query and table listing tools." Run it: mvn spring-boot:run Add to ~/Library/Application Support/Claude/claude desktop config.json : { "mcpServers": { "my-spring-server": { "command": "java", "args": "-jar", "/absolute/path/to/your-server.jar" } } } Restart Claude Desktop. You should see a 🔨 hammer icon in the chat input. Click it — your tool names should appear. Type: "List all the tables in the database" Claude calls your tool, your Spring Boot logs fire, Claude gets real data back. That's your first working MCP integration. Here's what burned me. There are two transports and they are not interchangeable: | Client | Transport | Maven starter | |---|---|---| | Claude Desktop, Claude Code CLI | stdio subprocess | spring-ai-starter-mcp-server | | VS Code, Cursor, Windsurf | SSE HTTP | spring-ai-starter-mcp-server-webmvc | The failure mode is brutal: no error message . Claude Desktop just shows no tools. VS Code just shows no server. The process starts fine. Logs look fine. The handshake silently fails. The rule: if the client is an IDE connecting over HTTP, use the webmvc starter. If the client is a CLI spawning your jar as a subprocess, use the plain starter without webmvc . For VS Code / Cursor, add to .vscode/mcp.json while the app is running: { "servers": { "my-spring-server": { "type": "sse", "url": "http://localhost:8080/sse" } } } 1. Guard against path traversal in file tools: Path target = BASE DIR.resolve userInput .normalize ; if target.startsWith BASE DIR return "Error: access denied"; 2. Guard against SQL writes: if sql.trim .toUpperCase .startsWith "SELECT" return "Error: only SELECT queries are permitted"; 3. Never return null from a @Tool method — return empty string instead. 4. Use absolute paths in your Claude Desktop config , not ~/ or ./ . 5. Add a docker-compose.yml so clients can run it with one command: services: mcp-server: build: . ports: - "8080:8080" environment: - SPRING DATASOURCE URL=${DB URL} - SPRING DATASOURCE USERNAME=${DB USER} - SPRING DATASOURCE PASSWORD=${DB PASSWORD} Everything above plus file system tools, REST API wrapper, and setup guides for both transports: → github.com/anirbandashfx-commits/spring-boot-mcp-server https://github.com/anirbandashfx-commits/spring-boot-mcp-server Building a custom MCP server for your Java team? → Connect on LinkedIn https://www.linkedin.com/in/anirbandas1986/