MCP Java Web Server Demo

基于 Spring Boot + Spring AI 构建的 MCP (Model Context Protocol) 服务器示例，使用 Streamable HTTP 传输协议，可对接 Claude Code 等 MCP 客户端。

版本要求

| 依赖 | 版本 | 说明 | |------|------|------| | JDK | >= 21 | 使用了 switch 表达式、文本块等语法特性 | | Spring Boot | 3.4.4 | 基础框架 | | Spring AI | 1.1.4 | 提供 MCP Server 自动配置和 @Tool 注解支持 | | MCP SDK | 0.17.0 | 由 Spring AI BOM 管理，无需手动指定 | | Maven | >= 3.9 | 项目自带 Maven Wrapper，无需全局安装 |

Spring AI >= 1.1.0 才支持 Streamable HTTP 协议。1.0.x 仅支持 SSE。

项目结构

src/main/java/com/example/mcp/
├── McpWebServerDemo.java   // Spring Boot 启动类
├── McpToolConfig.java      // @Configuration - Tool 注册配置
└── DemoTools.java          // @Service - 工具实现（业务逻辑）

内置 Tool 列表

| Tool 名称 | 功能 | 参数 | |-----------|------|------| | getCurrentTime | 获取当前日期时间 | 无 | | calculate | 四则运算 | a (数字), operator (+,-,*,/), b (数字) | | queryWeather | 查询城市天气 (Mock) | city (城市名) |

快速开始

1. 构建

./mvnw clean package -DskipTests

2. 启动服务

java -jar target/mcp-java-demo-web-1.0.0.jar

服务启动后，MCP 端点地址为 http://localhost:8080/mcp。

3. 对接 Claude Code

# 项目级 (生成 .mcp.json 文件，可提交 git)
claude mcp add --transport http --scope project mcp-web-demo http://localhost:8080/mcp

# 或全局级 (所有项目可用)
claude mcp add --transport http --scope user mcp-web-demo http://localhost:8080/mcp

重启 Claude Code 后即可使用。

配置说明

application.yml 完整配置参考

# ========================
# 服务器配置
# ========================
server:
  port: 8080                          # Web 服务端口，默认 8080

# ========================
# Spring AI MCP Server 配置
# ========================
spring:
  ai:
    mcp:
      server:
        # ---------- 基础配置 ----------
        name: mcp-web-demo             # MCP 服务名称，客户端连接时可见
        version: 1.0.0                 # MCP 服务版本号
        type: SYNC                     # 服务器类型：SYNC (同步) | ASYNC (异步)，默认 SYNC
        protocol: STREAMABLE           # 传输协议：STREAMABLE (推荐) | SSE (已废弃)

        # ---------- 能力开关 ----------
        capabilities:
          tool: true                   # 是否启用 Tool 能力，默认 true
          resource: true               # 是否启用 Resource 能力，默认 true
          prompt: true                 # 是否启用 Prompt 能力，默认 true
          completion: true             # 是否启用 Completion 能力，默认 true

        # ---------- 变更通知 ----------
        tool-change-notification: true      # Tool 变更时通知客户端，默认 true
        resource-change-notification: true  # Resource 变更时通知客户端，默认 true
        prompt-change-notification: true    # Prompt 变更时通知客户端，默认 true

        # ---------- Streamable HTTP 传输层配置 ----------
        streamable-http:
          mcp-endpoint: /mcp           # MCP 协议端点路径，默认 /mcp
          disallow-delete: false       # 是否禁止 DELETE 请求（关闭会话），默认 false
          keep-alive-interval: 30s     # SSE 长连接保活间隔，默认无

        # ---------- SSE 传输层配置 (仅 protocol=SSE 时生效) ----------
        sse-message-endpoint: /mcp/message  # SSE 消息端点，默认 /mcp/message
        base-url:                           # SSE 基础 URL，默认空

        # ---------- 注解扫描 ----------
        annotation-scanner:
          enabled: true                # 自动扫描 @Tool 注解的 Spring Bean，默认 true

当前项目实际使用的最小配置

server:
  port: 8080

spring:
  ai:
    mcp:
      server:
        name: mcp-web-demo
        version: 1.0.0
        protocol: STREAMABLE

大部分配置有合理的默认值，最小配置只需指定 name、version 和 protocol。

Claude Code MCP 配置方式

方式一：CLI 命令

# 查看已注册的 MCP Server
claude mcp list

# 添加（三种 scope）
claude mcp add --transport http --scope local   mcp-web-demo http://localhost:8080/mcp  # 项目级，写入 ~/.claude.json
claude mcp add --transport http --scope project mcp-web-demo http://localhost:8080/mcp  # 项目级，生成 .mcp.json 文件
claude mcp add --transport http --scope user    mcp-web-demo http://localhost:8080/mcp  # 全局级，写入 ~/.claude.json

# 删除
claude mcp remove mcp-web-demo

方式二：手动编辑 .mcp.json

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "mcp-web-demo": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

三种 transport type 对比

| type | 传输方式 | 配置字段 | 适用场景 | |------|---------|---------|---------| | stdio | 标准输入/输出 | command + args | 本地工具，Claude Code 自动管理进程 | | sse | Server-Sent Events | url | 已废弃，建议迁移到 http | | http | Streamable HTTP | url | 推荐，远程服务、团队共享 |

三种 scope 对比

| scope | 存储位置 | 说明 | |-------|---------|------| | local (默认) | ~/.claude.json 的 projects.{路径} 下 | 仅对指定项目路径生效，不在项目目录中创建文件 | | project | 项目根目录 .mcp.json | 可提交到 git，团队共享 | | user | ~/.claude.json 顶层 | 全局生效，所有项目可用 |

扩展指南

新增一个 Tool

1. 在 DemoTools（或新建 @Service 类）中添加方法：

@Tool(description = "Search user by ID")
public String searchUser(@ToolParam(description = "User ID") Long userId) {
    // 业务逻辑，可注入数据库、Redis、外部 API 等
    return userService.findById(userId).toString();
}

2. 如果是新的 @Service 类，在 McpToolConfig 中注册：

@Bean
public ToolCallbackProvider tools(DemoTools demoTools, UserTools userTools) {
    return MethodToolCallbackProvider.builder()
            .toolObjects(demoTools, userTools)
            .build();
}

3. 重新构建并启动即可，Claude Code 会自动发现新工具。