DEV Community

Anirban Das
Anirban Das

Posted on

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>
Enter fullscreen mode Exit fullscreen mode 
<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>
Enter fullscreen mode Exit fullscreen mode

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();
    }
}
Enter fullscreen mode Exit fullscreen mode

application.yml:

spring:
  ai:
    mcp:
      server:
        name: my-mcp-server
        version: 1.0.0
        instructions: "Provides database query and table listing tools."
Enter fullscreen mode Exit fullscreen mode

Run it:

mvn spring-boot:run
Enter fullscreen mode Exit fullscreen mode

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"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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";
Enter fullscreen mode Exit fullscreen mode

2. Guard against SQL writes:

if (!sql.trim().toUpperCase().startsWith("SELECT")) 
    return "Error: only SELECT queries are permitted";
Enter fullscreen mode Exit fullscreen mode

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}
Enter fullscreen mode Exit fullscreen mode

The full repo

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

Top comments (2)

Collapse
 
solonjava profile image
Solon Framework •

Thanks for this — the SSE vs stdio distinction is exactly the kind of detail that's easy to miss until you're staring at 'connection refused.'

One thing I find interesting about the MCP ecosystem right now is how the transport choice shapes the deployment model. A stdio transport means your server runs as a subprocess of the AI client, which is great for local dev but has different scaling characteristics than an SSE-based setup.

It feels like the framework-level abstractions around MCP are still evolving. Would be great to see more convention-over-configuration approaches where the server auto-detects the right transport based on the runtime context. Curious what transport pattern you've found most reliable in production so far.

Collapse
 
anirbandashfxcommits profile image
Anirban Das •

Yeah, that subprocess model took me a minute to wrap my head around too. stdio seems way easier at first since you don't have to manage servers or expose ports. But things get messy fast when the client owns your process lifecycle. Every time Claude Desktop restarts, you're hit with a cold start. Plus, you lose all shared state across sessions unless you manually save it somewhere.

Honestly, for anything outside of local dev, I've been sticking to SSE. Running the Spring Boot app as a real service and letting multiple IDEs connect just fits how Java teams actually deploy code. It also makes it way easier to hook into Spring Security if you need to lock down who can call specific tools.

The auto-detection idea sounds cool, but I'm skeptical about how clean it would actually be. The server can't really figure out the transport at runtime because it depends entirely on how it was launched. You’d basically need two entry points and a bunch of wrapper logic to check if stdin is a pipe or a terminal. Spring AI doesn't support that right now anyway.

To be honest, I'd just settle for better error messages. Right now, it just fails silently, which is a total nightmare for developer experience.

What does your setup look like? Are you putting SSE behind a gateway, or just connecting directly?