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

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:

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

Building a custom MCP server for your Java team?

→ Connect on LinkedIn