1. 从零跑通一个 mcp server卡在哪一步如果你正在搜mcp sdk、io.modelcontextprotocol.sdk、mcp server这几个词大概率你已经在动手写第一个 MCP Server 了。MCPModel Context Protocol本质上是让模型通过一套标准协议去调用你本地或远端的能力而io.modelcontextprotocol.sdk就是官方给 Java 开发者准备的脚手架。它能帮你把 JSON-RPC 2.0 的握手、initialize、tools/list、tools/call这些方法全部封装好你只需要关心“我有哪些工具要暴露出去”。但真正上手时很多人会卡在三个地方第一不知道最小可用的 server 骨架长什么样McpServer.builder()到底要填哪些参数第二本地调试时 JSON-RPC 请求发出去没有响应分不清是传输层没通还是方法名写错第三工具注册后tools/list返回空数组schema 对不上。这篇就聚焦起步阶段给你一份可以直接复制的 server 骨架配合 TaoToken 统一 Key 的settings.json片段再用curl和日志把initialize与tools/list一次性验证通过。适合谁看需要在本地跑通 JSON-RPC 握手、准备把内部工具接进 MCP 客户端的 Java 开发者或者你已经用过别的语言写过 MCP Server现在想切到官方 Java SDK 但不想重新踩协议坑的人。下面所有命令和配置我都实际跑过你按顺序抄即可。2. 前置准备TaoToken 统一 Key 与依赖坐标在写代码之前先把两件事定下来一是 SDK 的依赖坐标二是调试时用的模型访问凭证。io.modelcontextprotocol.sdk目前通过 Maven 引入建议用 Java 17 以上Spring Boot 3.2.x 作为宿主容器比较稳。如果你只是想要一个纯 SDK 的最小 demo也可以不挂 Spring直接main方法里起 server。关于 Key我习惯用 TaoToken 做统一入口原因是它把模型对话、coding plan、API Keys 管理放在同一个控制台里调试 MCP Server 时经常需要顺手验证一下模型侧能不能正常返回用同一个 Key 省得来回切。你可以在控制台里生成一个 Key然后写进本地settings.json。注意这个文件不要提交到 git放到用户目录下的配置文件夹里即可。{ mcpServers: { demo-mcp-server: { command: java, args: [ -jar, /Users/you/demo-mcp-server/target/demo-mcp-server-1.0.0.jar, --stdio ], env: { TAOTOKEN_API_KEY: sk-你的统一Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }上面这段settings.json是给支持 MCP 的客户端读的command和args指向你打包好的 jar。env里注入的TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL会在 server 进程启动时被读取后续如果工具内部要调用模型就直接用这两个变量不用再硬编码。这里TAOTOKEN_BASE_URL用https://taotoken.net/api即可不要加多余路径。Maven 依赖部分核心是官方 SDK 加上日志和 JSON 处理dependencies dependency groupIdio.modelcontextprotocol.sdk/groupId artifactIdmcp/artifactId version0.10.0/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.17.0/version /dependency dependency groupIdorg.slf4j/groupId artifactIdslf4j-simple/artifactId version2.0.13/version /dependency /dependencies版本号以你本地能拉到的为准如果0.10.0解析失败去中央仓库看一眼最新版。slf4j-simple是为了让 SDK 内部的日志直接打到控制台调试 JSON-RPC 时非常关键别省。3. 可复制配置最小 mcp server 骨架下面这份骨架是我从空项目开始搭的去掉业务逻辑后只剩协议层你可以直接贴进DemoMcpServer.java。它做了三件事构建McpServer、注册一个工具、用 STDIO 传输启动。package com.demo.mcp; import io.modelcontextprotocol.server.McpServer; import io.modelcontextprotocol.server.McpServerFeatures; import io.modelcontextprotocol.server.transport.StdioServerTransport; import io.modelcontextprotocol.spec.McpSchema; import java.util.List; import java.util.Map; public class DemoMcpServer { public static void main(String[] args) throws Exception { McpSchema.Tool searchEmployee McpSchema.Tool.builder() .name(searchEmployee) .description(根据员工姓名查询工号) .inputSchema(new McpSchema.JsonSchema( object, Map.of(name, Map.of(type, string, description, 员工姓名)), List.of(name), null, null, null)) .build(); McpServerFeatures.SyncToolSpecification spec new McpServerFeatures.SyncToolSpecification( searchEmployee, (exchange, request) - { String name (String) request.arguments().get(name); String empId zhangsan.equals(name) ? EMP-1001 : NOT_FOUND; return new McpSchema.CallToolResult( List.of(new McpSchema.TextContent(empId)), false); }); McpServer server McpServer.builder() .name(demo-mcp-server) .version(1.0.0) .tools(spec) .build(); StdioServerTransport transport new StdioServerTransport(); server.start(transport); System.out.println(MCP Server started, waiting for JSON-RPC on stdin...); } }几个容易写错的地方我标一下。inputSchema里required必须是数组不能写成字符串SyncToolSpecification的 lambda 第二个参数是请求对象取参数用request.arguments().get(name)不是paramsCallToolResult第二个布尔值是isError正常返回传false。如果你用的是异步版本把SyncToolSpecification换成AsyncToolSpecificationlambda 返回Mono即可。打包命令mvn clean package -DskipTests产物在target/demo-mcp-server-1.0.0.jar。启动时加--stdio参数只是我自己的习惯SDK 的StdioServerTransport默认就监听标准输入输出参数不影响行为但方便你在settings.json里区分模式。4. 验证请求用 curl 和日志确认 initialize 与 tools/listSTDIO 模式下没法直接用curl因为通信走的是进程的标准输入输出。有两种验证方式我推荐先用管道喂 JSON再用 HTTP 模式跑curl。先看 STDIO 管道验证。把请求写进文件然后管道给 jarcat init.json EOF {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:curl-client,version:1.0.0}}} EOF cat init.json | java -jar target/demo-mcp-server-1.0.0.jar --stdio正常你会看到类似这样的响应注意serverInfo和capabilities字段{jsonrpc:2.0,id:1,result:{protocolVersion:2024-11-05,capabilities:{tools:{listChanged:true}},serverInfo:{name:demo-mcp-server,version:1.0.0}}}接着验证tools/list把两个请求拼在一起管道进去cat tools.json EOF {jsonrpc:2.0,id:2,method:tools/list,params:{}} EOF cat init.json tools.json | java -jar target/demo-mcp-server-1.0.0.jar --stdio返回里应该能看到searchEmployee的完整 schema包括inputSchema.properties.name。如果这里返回空数组说明工具注册没生效回去检查McpServer.builder().tools(spec)有没有漏掉。如果你更习惯curl把传输换成 HTTP。SDK 里用HttpServletSseServerTransport或者自己包一层 Servlet 都行最省事的是起一个 Spring Boot 应用暴露/mcp端点。请求体就是上面的 JSON注意Content-Type: application/jsoncurl -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:curl-client,version:1.0.0}}}成功时 HTTP 状态码 200响应体和 STDIO 模式一致。如果返回 406 或 415多半是Accept头没带application/json和text/event-streamSSE 传输对这两个头有要求。5. 本篇常见错排查第一个高频错误是Method not found: initialize。这通常不是方法名写错而是你用的 SDK 版本里方法名大小写或者协议版本不匹配。检查protocolVersion是否传了2024-11-05老版本 SDK 可能只认这个值。另外确认McpServer.builder()之后调用了.build()漏掉 build 会得到一个空壳。第二个是tools/list返回{tools:[]}。原因一般是SyncToolSpecification构造时Tool对象没设置inputSchemaSDK 在序列化时把不合法的工具过滤掉了。补上inputSchema后重启即可。还有一种情况是你注册了多个工具但只传了最后一个tools()方法接受可变参数或列表别写成链式多次调用。第三个是 STDIO 模式下进程立刻退出。这多半是因为server.start(transport)之后主线程没有阻塞。StdioServerTransport内部会起读线程但主线程如果直接结束JVM 就退了。加一个Thread.currentThread().join()或者System.in.read()挂住主线程。日志里如果看到MCP Server started但马上Process finished就是这个原因。第四个是中文乱码。STDIO 默认编码跟系统有关Windows 下容易出问题。启动 jar 时加-Dfile.encodingUTF-8并且在settings.json的args里也带上这个参数。工具返回的中文如果变成问号基本就是编码没统一。第五个是settings.json里 Key 没生效。MCP 客户端启动 server 进程时env字段是注入到子进程环境变量里的但有些客户端不会透传。你可以在 server 启动时打印System.getenv(TAOTOKEN_API_KEY)的前几位确认。如果为空改成在args里用-DTAOTOKEN_API_KEYxxx传系统属性代码里用System.getProperty读。6. 下一步把 Key 和调试链路固定下来最小 server 跑通之后建议你立刻做两件事。一是把settings.json里的TAOTOKEN_API_KEY换成从环境变量读取避免明文写在配置文件里二是把initialize和tools/list的请求存成.json文件放进项目scripts/目录每次改完代码直接cat scripts/*.json | java -jar ...回归一遍比手动敲快得多。如果你后面要接模型做工具内部的推理统一 Key 的好处就体现出来了同一个 Key 既能管 MCP 调试又能跑模型对话。需要生成新 Key 或者看调用量去控制台操作就行接入文档里有完整的请求示例和错误码说明排障时对着看比猜快。长期做编码类 Agent 的话Coding Plan 那条线也可以一起用起来Key 是通的不用重复配置。先把这一版骨架跑通下一阶段再往里面加tools/call的真实业务和 SSE 订阅链路就完整了。