1. 为什么 MCP HTTP 传输值得单独聊一次MCP 全称 Model Context Protocol是让大模型调用外部工具、读取资源的一套标准协议。它本身不绑定传输方式官方目前给了三种Stdio、SSE、HTTP。Stdio 适合本地进程SSE 适合远程推送而 HTTP 传输是三者里实现门槛最低的一种——它把 SSE 的双通道长连接砍成单通道客户端发一个 POST服务端在同一次连接里把结果返回不需要维护 pendingResponses 映射也不需要 CompletableFuture 做异步匹配。听起来很省事但真正动手写的时候很多人会在同一个地方卡住明明用的是标准 HTTP响应体却是 SSE 格式的文本。你拿到的不是{jsonrpc:2.0,...}而是event: message加一行data: {...}。直接丢给 JSON 解析器立刻抛JsonParseException: Unexpected character (e)。这个坑不解决后面 tools/list、tools/call 全都跑不通。这篇面向的是需要对接支持 HTTP 传输的 MCP 服务、或者想搞清楚三种传输差异的 Java 开发者。我会用 OkHttp 从零搭一个可运行的客户端把 JSON-RPC 请求体、Accept 头、session 管理、SSE 响应解析全部写成可复制的代码然后把 endpoint 切到 TaoToken 统一 Key 通道演示 401 和 local proxy failed 这两类报错怎么一步步定位。适合谁手上有 MCP 服务端、想用 Java 接进来、又不想被传输层细节反复折磨的人。2. TaoToken 统一 Key 通道前置准备在写 OkHttp 代码之前先把请求要打到哪里确定下来。MCP 服务端如果自己部署endpoint 就是你的服务地址如果走统一通道可以用 TaoToken 的 API 入口。它的作用是给多个模型和工具提供一个统一的 Key 和 Base URL省得每个服务单独配一套鉴权。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数直接写就行。你需要准备三样东西我把它叫「三件套」配置项取值来源在 MCP HTTP 里的位置Base URLhttps://taotoken.net/apiOkHttp 请求的.url()API Key控制台生成的 Key请求头Authorization: Bearer keyModel ID你要调用的模型标识JSON-RPC params 里的 model 字段Key 的生成入口在控制台的 API Keys 页面路径是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。生成后复制出来后面 OkHttp 拦截器里要用。这里有个容易忽略的点MCP 的 HTTP 传输和普通 REST 请求不一样它要求Accept头同时声明application/json和text/event-stream。只写前者部分服务端会直接返回 406。所以你在配 OkHttp 的时候不能只设Content-TypeAccept必须显式写全。如果你还没决定用哪种传输可以先在模型对话页面手动发一次请求确认 Key 和 Base URL 是通的地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。确认通了再回到代码层能省掉一半排查时间。另外长期跑编码类 Agent 或者需要反复调工具的可以看下 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它和单次 API 调用的区别在于配额和并发策略MCP 这种会连续发多个 JSON-RPC 请求的场景用套餐比按次更稳。前置准备做完你手上应该有一个可用的 Base URL、一个 API Key、一个 Model ID。接下来进入代码。3. 可复制的 OkHttp 配置与 JSON-RPC 请求体这一节是全文的核心所有代码都能直接粘进项目跑。我按「客户端构建 → 请求发送 → 响应解析」三段来写每段都标了关键参数。3.1 OkHttpClient 构建与 session 拦截器MCP HTTP 传输的第一次请求initialize会在响应头里返回mcp-session-id后续所有请求都要带上它。用拦截器统一处理避免每个方法里重复写。public McpHttpConnection(String serverName, ServerConfig config) { super(serverName, config); this.baseUrl config.url; this.apiKey config.apiKey; this.httpClient new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .addInterceptor(chain - { Request original chain.request(); Request.Builder builder original.newBuilder() .header(Authorization, Bearer apiKey) .header(Accept, application/json, text/event-stream); Response response chain.proceed(builder.build()); String mcpSessionId response.header(mcp-session-id); if (mcpSessionId ! null) { if (sessionId null) { sessionId mcpSessionId; log.info([{}] 收到 session_id{}, serverName, sessionId); } else if (!sessionId.equals(mcpSessionId)) { log.warn([{}] session_id 变更{} → {}, serverName, sessionId, mcpSessionId); sessionId mcpSessionId; } } return response; }) .build(); }注意Accept头写的是两个值中间用逗号加空格分隔。这是 MCP HTTP 传输的硬性要求缺了text/event-stream服务端会拒绝。3.2 JSON-RPC 请求体与发送方法每次请求的结构固定POST Content-Type: application/json 可选的mcp-session-id。private String sendHttpRequest(String jsonBody) throws IOException { RequestBody body RequestBody.create( jsonBody, MediaType.get(application/json; charsetutf-8)); Request.Builder builder new Request.Builder() .url(baseUrl) .post(body) .header(Content-Type, application/json); if (sessionId ! null) { builder.header(mcp-session-id, sessionId); } try (Response response httpClient.newCall(builder.build()).execute()) { if (!response.isSuccessful()) { String errorBody response.body() ! null ? response.body().string() : ; lastError String.format(HTTP %d: %s, response.code(), errorBody); throw new IOException(lastError); } return response.body() ! null ? response.body().string() : {}; } }一个 initialize 请求的 JSON-RPC 体长这样{ jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: { name: okhttp-mcp-client, version: 1.0.0 } } }id用来匹配请求和响应method是 MCP 定义的方法名params按方法不同而变。tools/list 的 params 可以是空对象tools/call 则要带工具名和参数。3.3 SSE 格式响应解析这是最容易踩坑的地方。响应体不是纯 JSON而是 SSE 文本event: message data: {jsonrpc:2.0,id:1,result:{protocolVersion:2024-11-05}}解析逻辑要兼容两种格式纯 JSON 和 SSE。private String parseSseResponse(String sseText) throws IOException { if (sseText null || sseText.trim().isEmpty()) { return {}; } if (!sseText.contains(data:)) { return sseText.trim(); } StringBuilder jsonData new StringBuilder(); try (BufferedReader reader new BufferedReader(new StringReader(sseText))) { String line; while ((line reader.readLine()) ! null) { line line.trim(); if (line.startsWith(data:)) { String data line.substring(5).trim(); if (jsonData.length() 0) { jsonData.append(\n); } jsonData.append(data); } } } String result jsonData.toString().trim(); if (result.isEmpty()) { throw new IOException(SSE 响应中没有 data 字段 sseText); } return result; }把发送和解析串起来public synchronized McpResponse sendRequest(String method, Object params) throws Exception { if (!connected) { throw new IllegalStateException(未建立连接 serverName); } McpRequest request new McpRequest(); request.id nextRequestId(); request.method method; request.params params; String requestJson mapper.writeValueAsString(request); String responseText sendHttpRequest(requestJson); String responseJson parseSseResponse(responseText); McpResponse response mapper.readValue(responseJson, McpResponse.class); if (response.error ! null) { throw new McpException(response.error.code, response.error.message, response.error.data); } return response; }到这里一个完整的 MCP HTTP 客户端就成型了。核心只有四步POST 发请求、拦截器取 session_id、解析 SSE 格式响应、DELETE 清理 session。比 SSE 传输少了 pendingResponses 映射和 Future 匹配代码量大概少三分之一。4. 验证请求与成功结果对照代码写完不能只看编译通过要实际发一次请求对照预期输出。这一节给你完整的验证动作和每一步应该看到什么。4.1 第一步initialize 握手发送 initialize 请求观察响应头和响应体。McpResponse initResp connection.sendRequest(initialize, Map.of( protocolVersion, 2024-11-05, capabilities, Map.of(), clientInfo, Map.of(name, okhttp-mcp-client, version, 1.0.0) ));预期结果响应头里出现mcp-session-id: 一串 UUID拦截器日志打印「收到 session_idxxx」响应体解析后result.protocolVersion等于2024-11-05result.serverInfo.name是你对接的服务名如果这一步就报 401先别改代码去看第 5 节的排查。4.2 第二步发送 initialized 通知MCP 协议要求 initialize 之后发一个 initialized 通知它没有 id也不需要读响应。MapString, Object notification new HashMap(); notification.put(jsonrpc, 2.0); notification.put(method, notifications/initialized); notification.put(params, Map.of()); sendHttpRequest(mapper.writeValueAsString(notification));预期HTTP 200响应体可能是空或者{}。这一步不解析 JSON-RPC 响应因为通知本来就没有对应响应。4.3 第三步tools/list 拉工具列表McpResponse toolsResp connection.sendRequest(tools/list, Map.of());预期输出{ jsonrpc: 2.0, id: 2, result: { tools: [ { name: get_weather, description: ..., inputSchema: {...} } ] } }如果tools数组为空说明服务端没注册工具不是客户端问题。4.4 第四步tools/call 实际调用McpResponse callResp connection.sendRequest(tools/call, Map.of( name, get_weather, arguments, Map.of(city, Beijing) ));预期result.content里是工具返回的内容数组。到这里整条链路就通了。4.5 第五步DELETE 清理 sessionRequest request new Request.Builder() .url(baseUrl) .delete() .header(mcp-session-id, sessionId) .header(Accept, application/json, text/event-stream) .build(); try (Response response httpClient.newCall(request).execute()) { log.info(session 清理完成状态码{}, response.code()); }预期状态码 200 或 204。清理失败不影响功能但长期跑会积累无效 session。把 endpoint 换成 TaoToken 统一通道后这五步的预期输出完全一样区别只在 Base URL 和 Authorization 头。如果换了之后某一步失败对照下一节排查。5. 本篇常见错误排查401、local proxy failed 与解析异常这一节按真实报错来组织每条都给你症状、原因、解决动作。5.1 401 Unauthorized症状initialize 请求返回 401响应体可能是{error:invalid api key}或类似。原因有三种Key 没带、Key 写错、Key 和 Base URL 不匹配。MCP HTTP 传输里Authorization 头是在拦截器里加的如果你在sendHttpRequest里又手动加了一次可能覆盖成空值。解决动作打印实际发出的请求头确认Authorization: Bearer key存在且 Key 完整检查 Base URL 是不是https://taotoken.net/api不要多写或少写路径去控制台 API Keys 页面重新生成一个 Key排除复制时带了空格5.2 local proxy failed症状请求还没到服务端就失败日志里出现local proxy failed或连接被拒绝。原因本地网络层拦截了请求常见于系统代理配置、环境变量HTTP_PROXY/HTTPS_PROXY被设置、或者 OkHttp 走了默认代理。解决动作检查环境变量临时清掉HTTP_PROXY和HTTPS_PROXY再跑在 OkHttpClient 构建时显式设置.proxy(Proxy.NO_PROXY)强制不走代理用 curl 直接打 Base URL确认网络层本身是通的this.httpClient new OkHttpClient.Builder() .proxy(Proxy.NO_PROXY) .connectTimeout(10, TimeUnit.SECONDS) .build();5.3 JsonParseException: Unexpected character (e)症状解析响应体时抛异常提示遇到字符e。原因响应体是 SSE 格式以event:开头直接当 JSON 解析当然失败。解决动作所有响应体先过parseSseResponse()再交给 Jackson。这个方法同时兼容纯 JSON 和 SSE不要跳过。5.4 406 Not Acceptable症状第一次请求就返回 406。原因Accept头只写了application/json没写text/event-stream。解决动作确认拦截器里Accept是application/json, text/event-stream两个值都在。5.5 后续请求 401 或 403症状initialize 成功tools/list 返回 401。原因session_id 没带上。服务端用 session 维持上下文不带 session 的请求被当成新连接或未授权。解决动作确认拦截器在响应头里取到了mcp-session-id并且后续请求的mcp-session-id头有值。打印sessionId变量确认非空。5.6 OAuth 相关报错症状日志里出现OAuth或token expired。原因部分 MCP 服务端用 OAuth 做鉴权Key 过期或 scope 不对。解决动作重新走一次授权流程拿新 token或者换用 API Key 鉴权模式。TaoToken 统一通道用的是 Bearer Key不涉及 OAuth 跳转如果你从别的服务切过来记得把鉴权方式改掉。排查顺序建议先看 HTTP 状态码再看响应体最后看请求头。大部分问题在请求头这一层就能定位。6. 把 endpoint 切到 TaoToken 后的接入收尾前面所有代码默认 endpoint 是可配置的。切到 TaoToken 统一 Key 通道只需要改三个地方Base URL、API Key、Model ID。这就是前面说的三件套缺一不可。ServerConfig config new ServerConfig(); config.url https://taotoken.net/api; config.apiKey System.getenv(TAOTOKEN_API_KEY); config.modelId your-model-id;Model ID 在 JSON-RPC 的 params 里传具体字段名看服务端实现。有些 MCP 服务端把 model 放在 tools/call 的 arguments 里有些放在 initialize 的 capabilities 里按你的服务端文档来。如果你用的是 Claude Code 这类工具接入配置在 settings 文件里Base URL 填https://taotoken.net/apiKey 填控制台生成的Model ID 填你要用的模型。三件套写全不要只填 URL 和 Key 漏掉 Model ID否则请求会返回模型不存在的错误。验证接入是否成功最快的办法是回到第 4 节的五步验证从 initialize 走到 tools/call。五步都过说明通道是通的。如果卡在某一步回到第 5 节对照报错。长期跑 Agent 或者需要连续调工具的建议看下 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。MCP 场景下请求是连续发的单次 API 调用容易在并发上受限套餐的配额策略更适合这种模式。最后给一个实用技巧把parseSseResponse单独抽成工具方法加单元测试输入纯 JSON 和 SSE 两种文本断言输出一致。这个测试能帮你挡住后面 80% 的解析类报错。我试过在三个不同 MCP 服务端上跑同一套客户端代码只要 Accept 头和 SSE 解析这两处写对切换服务端基本不用改代码。