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

#mcp #springboot #java #llm

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.

What MCP actually is (in 60 seconds)

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.

The full working server (copy-paste ready)

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

Testing it: connect to Claude Desktop

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.

THE TRAP: SSE vs stdio

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"
    }
  }
}

Production checklist before you ship

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}