摘要：最近在 VS Code 中配置 MCP（Model Context Protocol）连接本地 Java 服务时，遇到了 Unrecognized field "form" 的序列化错误。本文详细记录从报错分析、版本兼容性排查到最终解决的完整过程，希望能帮到有同样困扰的开发者。

Git 仓库： langchain4j-spring-agent/langchain4j-spring-ai/langchain4j-spring-ai-swagger-mcp

---

一、问题现象

在 VS Code 的 mcp.json 中配置了两个 MCP 服务：

• SwaggerMcp：自定义 Java MCP 服务，用于管理 Swagger API（HTTP SSE 类型）
• dbhub：Bytebase 的数据库管理 MCP 服务（STDIO 类型）

{
  "servers": {
    "SwaggerMcp": {
      "url": "http://127.0.0.1:3000/sse"
    },
    "io.github.bytebase/dbhub": {
      "type": "stdio",
      "command": "npx",
      "args": ["@bytebase/dbhub@0.13.2"],
      "env": {
        "DSN": "mysql://root:secretmysql@localhost:3306/langchain4j-spring-ai-seg"
      }
    }
  }
}

启动后，dbhub 工作正常，但 SwaggerMcp 报错：

2026-02-11 14:20:28.310 [info] 404 status sending message to http://127.0.0.1:3000/sse , will attempt to fall back to legacy SSE
2026-02-11 14:20:28.322 [error] Error: MPC -32603: Unrecognized field "form" 
(class io.modelcontextprotocol.spec.McpSchema$ClientCapabilities$Elicitation), 
not marked as ignorable (0 known properties: ])

错误堆栈显示：客户端发送的 capabilities 对象中包含了服务端不认识的 form 字段。

---

二、根因分析

2.1 错误解读

这个错误是典型的 Jackson 反序列化失败。VS Code 的 MCP 客户端（较新版本）在初始化时发送的 JSON 结构如下：

{
  "capabilities": {
    "elicitation": {
      "form": true  // ← 服务端不认识这个字段！
    }
  }
}

而我的 Java 服务端使用的 MCP SDK 版本较老，生成的 Elicitation 类是空实现（0 known properties），无法识别客户端发来的 form 字段。

2.2 版本兼容性矩阵

查阅 modelcontextprotocol/java-sdk 官方仓库后发现：

MCP SDK 版本	支持的协议特性	说明
0.16.0	基础工具、资源、提示	❌ 不支持 elicitation.form
0.17.0+	新增 Elicitation 能力协商	✅ 支持表单式用户交互
0.17.2	修复序列化兼容性	✅ 推荐版本

根本原因是：VS Code 的 MCP 客户端已经升级到支持 elicitation 能力的新版本，而我的 Java 服务端还停留在 0.16.0，导致协议握手失败。

---

三、解决方案

3.1 升级依赖版本

将 pom.xml 中的 MCP SDK 从 0.16.0 升级到 0.17.2，同时升级 Spring AI 到 2.0.0-SNAPSHOT：

原配置（报错）：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-bom</artifactId>
    <version>1.1.0</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-bom</artifactId>
    <version>0.16.0</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

新配置（修复）：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-bom</artifactId>
    <version>2.0.0-SNAPSHOT</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-bom</artifactId>
    <version>0.17.2</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

3.2 添加快照仓库

由于 Spring AI 2.0.0 尚未发布正式版，需要添加快照仓库：

<repositories>
    <repository>
        <id>spring-snapshots</id>
        <name>Spring Snapshots</name>
        <url>https://repo.spring.io/snapshot</url>
        <releases>
            <enabled>false</enabled>
        </releases>
    </repository>
</repositories>

3.3 验证修复

升级后重启 Java 服务，VS Code 中 MCP 连接成功，不再报错。可以通过以下方式验证：

1. 查看 VS Code Output 日志：确认没有 Unrecognized field 错误
2. 测试工具调用：在 Copilot Chat 中使用 @SwaggerMcp 调用 API 管理工具
3. 检查服务端日志：确认收到 initialize 请求并正常响应

---

四、深度解析：MCP 协议演进

4.1 Elicitation 能力是什么？

根据 MCP 官方文档，Elicitation 是 2025 年协议新增的能力，允许服务器向客户端请求额外的用户信息（如表单输入）。

// 0.17.0+ 的 Elicitation 类结构
public record Elicitation(
    Boolean form,      // 支持表单式交互
    Boolean prompt     // 支持提示式交互
) {}

4.2 为什么 0.16.0 会报错？

0.16.0 版本的 Elicitation 类是空实现：

// 0.16.0 - 空类，没有任何字段
public static class Elicitation {
    // 0 known properties
}

当客户端发送包含 form: true 的 JSON 时，Jackson 无法绑定到空类，抛出 Unrecognized field 异常。

4.3 版本升级注意事项

升级到 0.17.2 后，需要注意以下 Breaking Changes：

变更项	0.16.0	0.17.2	影响
传输协议	SSE 为主	支持 Streamable HTTP	需要检查端点配置
端点路径	/sse	可配置 /mcp	更新 application.yml
超时设置	默认 5s	可配置 5min	长耗时工具需要调整

推荐配置（application.yml）：

spring:
  ai:
    mcp:
      server:
        enabled: true
        name: swagger-mcp-server
        version: 1.0.0
        protocol: STREAMABLE  # 或 SSE，根据客户端支持选择
        sse-message-endpoint: /mcp/messages

---

五、最佳实践建议

5.1 版本锁定策略

MCP 协议目前处于快速迭代期，建议：

1. 客户端与服务端版本对齐：VS Code 插件、Java SDK、Python SDK 保持相近版本
2. 关注官方 Release Note：特别是 capabilities 相关的变更
3. 使用 BOM 管理依赖：避免版本冲突

5.2 调试技巧

遇到类似序列化错误时，可以：

1. 开启 DEBUG 日志：

logging:
  level:
    io.modelcontextprotocol: DEBUG

2. 抓包查看协议交互：

# 使用 tcpdump 或 Wireshark 查看 SSE 流
curl -N http://localhost:3000/sse

3. 检查 VS Code MCP 面板：查看客户端发送的原始 JSON 结构

5.3 参考资源

• Spring AI MCP 官方示例
• MCP Java SDK 文档
• MCP 协议规范

---

六、总结

这次踩坑的核心教训是：MCP 作为新兴协议，版本兼容性至关重要。客户端和服务端的 SDK 版本差异会导致协议握手失败，表现为各种序列化错误。

关键解决步骤：

1. ✅ 升级 MCP Java SDK 至 0.17.2
2. ✅ 升级 Spring AI 至 2.0.0-SNAPSHOT
3. ✅ 检查并更新服务端配置

希望这篇文章能帮你少走弯路！如果你也遇到类似的 MCP 兼容性问题，欢迎在评论区交流。

---

参考链接：

• (https://github.com/modelcontextprotocol/java-sdk) MCP Java SDK 官方仓库
• (https://github.com/spring-projects/spring-ai-examples) Spring AI 官方示例
• (https://docs.mcpcn.org/sdk/java/mcp-overview) MCP 中文文档

---

📌 提示：MCP 协议仍在快速发展中，建议关注官方仓库的 Release 页面，及时获取版本更新信息。生产环境使用时，建议锁定具体版本号，避免自动升级带来的兼容性问题。

---