spring-boot-mcp-server

Spring Boot MCP Server Sample

A demonstration of Atmosphere's MCP (Model Context Protocol) server module. AI agents like Claude Desktop, VS Code Copilot, or Cursor connect via Streamable HTTP or WebSocket and invoke tools, read resources, and use prompt templates.

What It Does

The DemoMcpServer exposes:

Tools (agents can call these):

• list_users — list all users currently connected to the chat
• ban_user — disconnect and ban a user from the chat by UUID
• broadcast_message — send a message to all connected chat users
• send_message — send a private message to a specific user by UUID
• atmosphere_version — return the Atmosphere framework version and runtime info

Resources (agents can read these):

• atmosphere://server/status — server status and uptime
• atmosphere://server/capabilities — what the server can do

Prompts (reusable prompt templates):

• chat_summary — summarize current chat status
• analyze_topic — analyze a topic with configurable depth

Running

./mvnw spring-boot:run -pl samples/spring-boot-mcp-server

The MCP endpoint is available at http://localhost:8083/atmosphere/mcp.

Supported Transports

Transport	URL
Streamable HTTP (recommended)	POST http://localhost:8083/atmosphere/mcp
WebSocket	ws://localhost:8083/atmosphere/mcp
SSE	GET http://localhost:8083/atmosphere/mcp

Connecting MCP Clients

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "atmosphere-demo": {
      "url": "http://localhost:8083/atmosphere/mcp"
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "atmosphere-demo": {
      "url": "http://localhost:8083/atmosphere/mcp"
    }
  }
}

Cursor

Add to Cursor Settings → MCP Servers:

{
  "mcpServers": {
    "atmosphere-demo": {
      "url": "http://localhost:8083/atmosphere/mcp"
    }
  }
}

stdio Bridge (for clients that only support stdio)

# Build the bridge JAR
cd modules/mcp && mvn package -Pstdio-bridge -DskipTests

# Configure your client:
{
  "mcpServers": {
    "atmosphere-demo": {
      "command": "java",
      "args": ["-jar", "path/to/atmosphere-mcp-4.0.0-SNAPSHOT-stdio-bridge.jar",
               "http://localhost:8083/atmosphere/mcp"]
    }
  }
}

Testing with curl

# Initialize session
curl -s -X POST http://localhost:8083/atmosphere/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"curl","version":"1.0"}}}'

# List tools (include Mcp-Session-Id from initialize response header)
curl -s -X POST http://localhost:8083/atmosphere/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Call a tool
curl -s -X POST http://localhost:8083/atmosphere/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_users","arguments":{}}}'

Server Code

The entire server is a single annotated class — see DemoMcpServer.java.

@McpServer(name = "atmosphere-demo", path = "/atmosphere/mcp")
public class DemoMcpServer {

    @McpTool(name = "list_users", description = "List all users connected to the chat")
    public List<Map<String, String>> listUsers() { ... }

    @McpTool(name = "broadcast_message", description = "Send a message to all chat users")
    public Map<String, Object> broadcastMessage(
            @McpParam(name = "message") String message) { ... }

    @McpResource(uri = "atmosphere://server/status", ...)
    public String serverStatus() { ... }

    @McpPrompt(name = "chat_summary", ...)
    public List<McpMessage> chatSummary() { ... }
}

React Frontend

The sample includes a React frontend (frontend/) built with the useAtmosphere hook from atmosphere.js/react. It provides a live chat UI where human users interact in real-time — while AI agents simultaneously connect via MCP to invoke tools like list_users, broadcast_message, and ban_user.

import { useAtmosphere } from 'atmosphere.js/react';

const { data, state, push } = useAtmosphere<ChatMessage>({
  request: {
    url: '/atmosphere/chat',
    transport: 'websocket',
    contentType: 'application/json',
  },
});

See the React, Vue, Svelte Hooks documentation for the full hooks API.

Key Concepts

• @McpServer — marks the class and sets the endpoint path
• @McpTool — exposes a method as a callable tool
• @McpResource — exposes a method as a read-only resource
• @McpPrompt — exposes a method as a prompt template
• @McpParam — annotates method parameters with metadata

The MCP module uses Atmosphere's transport layer, so agents get automatic reconnection, heartbeats, and transport fallback for free.