# 01、现场：Java系统如何被Codex调用

![开场问题链路](https://developer.qcloudimg.com/http-save/yehe-9261324/1d9f400a75a8074876de8cc479940263.png)

Codex CLI是OpenAI的本地编码代理，官方仓库说明它运行在终端，也可在IDE中使用。它本身不负责理解业务系统，需要外部能力时走MCP这类标准协议。

Java侧有官方MCP Java SDK，Spring AI在其上提供Spring Boot Starter。

做法是把已有Java接口注册成MCP工具，让Codex在对话中按需调用。

本文以查询文章标题是否重名、上传ZIP包两个接口为例，前者是只读短请求，后者是有状态、耗时、带副作用的写操作。

---

# 02、拆题：三个边界要先划清

协议边界：MCP定义工具、资源、提示等能力，传输可选STDIO、SSE、Streamable-HTTP。Spring AI文档明确SSE自2.0.0起弃用，应改用STREAMABLE。

进程边界：STDIO随宿主进程启动，HTTP适合独立部署、多客户端连接。Codex通过HTTP访问时，服务可独立升级。

安全边界：Spring AI文档写明HTTP传输默认暴露未认证的JSON-RPC端点，任何能访问该端点的客户端都能枚举并调用全部已注册工具。

注册上就能用只对本地开发成立，出localhost之前必须加安全层。

---

# 03、原理：注解如何变成工具

Spring AI的MCP Server Boot Starter提供自动配置，扫描带MCP注解的Bean并注册。

核心注解是@McpTool，参数用@McpToolParam描述，SDK据此生成JSON Schema。

服务端分同步与异步：SYNC用McpSyncServer，ASYNC用McpAsyncServer。

文档提醒SYNC只注册同步注解方法，ASYNC只注册异步方法，混写会被忽略。

底层Java SDK默认用Jackson做JSON，异步基于Reactive Streams与Reactor，服务端核心传输用Jakarta Servlet，授权只留可插拔钩子。

---

# 04、取舍：同步还是异步，STDIO还是HTTP

查询重名这类毫秒级接口适合SYNC：代码直白，代价是长任务占线程。ZIP上传适合ASYNC：不阻塞、可流式，代价是调试与异常传播更复杂。

STDIO适合本地单机、随客户端启动，无网络暴露面，但不能多客户端共享。

Streamable-HTTP适合团队共享、独立部署，支持多连接与流式，但必须自行加认证授权。

务实组合是查询走SYNC、上传走ASYNC、传输统一STREAMABLE，安全交给Spring Security。

---

# 05、架构：两层服务与一条安全边界

![两层服务与安全边界](https://developer.qcloudimg.com/http-save/yehe-9261324/3dc2b2423b92b91aae8a404d939b0f12.png)

整体分三层：Codex作为MCP客户端，Java MCP服务作为协议适配层，业务系统在其后。MCP服务不写业务逻辑，只做参数校验、身份透传和结果整形。

查询工具入参是标题，出参是是否重名与命中数量。

上传工具入参是文件名与内容，出参是任务ID，解压与入库异步执行。

身份透传用McpTransportContext：TransportContextExtractor从请求头取Authorization，工具方法经McpSyncRequestContext读取。

异常路径要显式设计：参数非法返回可读错误，下游超时返回可重试提示，权限不足直接拒绝。

---

# 06、实战：两个工具的最小实现

引入WebMVC的Starter，把协议设为STREAMABLE，服务类型设为SYNC。查询工具保持同步，描述写清只读，降低误调用概率。

```java
@McpTool(name = "check_title_duplicate",
         description = "查询文章标题是否已存在，只读")
public DuplicateResult checkTitle(
        @McpToolParam(description = "文章标题", required = true)
        String title) {
    return service.checkDuplicate(title);
}
```

上传工具返回任务ID而非最终结果，避免一次调用长时间挂起。

```java
@McpTool(name = "upload_zip",
         description = "上传ZIP包并异步解析，返回任务ID")
public UploadResult uploadZip(
        @McpToolParam(description = "文件名", required = true)
        String fileName,
        @McpToolParam(description = "Base64内容", required = true)
        String contentBase64) {
    byte[] bytes = Base64.getDecoder().decode(contentBase64);
    return service.submit(fileName, bytes);
}
```

工程上还要补三件事：限制包大小、校验扩展名、把解压放到隔离目录。这些校验放在工具入口，不指望模型自觉遵守描述。

---

# 07、复盘：测试要覆盖协议而非只测方法

第一层单元测试直接测Service，验证重名判定与ZIP校验规则。第二层工具契约测试，确认注解生成的Schema包含必填项与描述。

第三层协议一致性：Java SDK仓库提供conformance-tests，服务端套件当前40/40通过。

可按仓库说明启动本地服务，再用官方conformance工具跑active套件。

第四层端到端：在Codex中发起对话，观察它是否选对工具、参数是否合法。

安全测试别漏：未带凭证直接请求端点，应被拒绝而不是返回工具列表。

---

# 08、洞见：生态位置与商业边界

MCP把系统能力变成可被多个AI客户端复用的标准接口，这是一次解耦。对Java团队，价值不在写一个工具，而在把存量接口低成本地暴露出去。

Spring AI的注解模型降低了门槛，但也带来风险：注册即暴露。

官方文档反复强调默认无认证，治理成本从写代码转移到管权限。

商业上，可复用的MCP服务更像内部能力市场，按工具粒度授权、计量和审计。

官方参考服务器明确说明它们只是教学示例，不是生产方案，生产系统仍需自己的限流、审计与故障隔离。

Codex侧的具体插件配置方式，本文未取得官方细节，落地前应查其官方文档确认。

---

# 09、小结：先跑通一条只读链路

![总结判断流程](https://developer.qcloudimg.com/http-save/yehe-9261324/4f1367e3d6162e99b24945e505bca0df.png)

建议顺序是：先用SYNC加STREAMABLE跑通查询重名，确认Codex能正确选工具。再加安全边界，验证未授权请求被拒，然后才接入上传这类写操作。

上传务必异步化并返回任务ID，把长耗时与协议请求解耦。

测试以协议一致性为底线，以对话端到端为验收。

延伸阅读可查MCP Java SDK的Server章节、Spring AI的MCP Server Boot Starter章节、MCP规范的Transports章节，以及Codex官方文档的MCP配置章节。

Codex CLI是OpenAI的本地编码代理，官方仓库说明它运行在终端，也可在IDE中使用。它本身不负责理解业务系统，需要外部能力时走MCP这类标准协议。

如何使用java框架开发一个MCP服务并对接上codex的插件？

用Spring AI MCP Server Starter把Java接口暴露为MCP工具，以文章重名查询和ZIP上传为例，讲清架构、工程、测试与生态边界。

架构师

人工智能

查询重名用同步、ZIP上传走异步、传输统一STREAMABLE，加SpringSecurity防未授权访问。核心是把Java接口注册成MCP工具，测试覆盖协议一致性而非仅方法逻辑。生产系统需自建限流审计，先用只读链路验证Codex调用再扩展写操作。

安全测试

单元测试

代码解释

服务器

JSON

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

如何使用java框架开发一个MCP服务并对接上codex的插件？-腾讯云开发者社区-腾讯云

如何使用java框架开发一个MCP服务并对接上codex的插件？

如何使用java框架开发一个MCP服务并对接上codex的插件？

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐