服务注册与分布式协调 / 系统课时
用 Java 框架自动注册 MCP
用 Java 框架自动注册 MCP
这一篇把一个最小 Java MCP Server 接到 Nacos:定义一个工具、启用 Spring AI Alibaba 的 Nacos 注册能力、启动应用,再通过管理 API 验证服务目录中已经出现对应条目。完成后,新实例启动即可走同一条标准注册路径。
学习目标
- 配置 Spring AI Alibaba 与 Spring AI MCP Server 的最小依赖。
- 将 Java 方法暴露为 MCP Tool,并在应用启动时自动注册到 Nacos。
- 用目录 API 验证服务名称、版本和注册结果是否已经进入 Nacos。
准备兼容的工程依赖
Nacos 当前自动注册手册使用 spring-ai-alibaba-starter-mcp-registry 配合 Spring AI 的 MCP Server starter,并通过 spring.ai.alibaba.mcp.nacos.register.enabled 开启注册。([Nacos 官网][2]) 本示例固定在 Spring AI Alibaba 1.1.2.2、Spring AI 1.1.2 与 Spring Boot 3.5.8 这一组对齐版本;Spring AI Alibaba 1.1.2.x 的发布与主仓库都将 Spring AI 基线对齐到 1.1.2。([GitHub][3])
pom.xml 使用完整的可启动配置:
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.8</version>
<relativePath/>
</parent>
<groupId>dev.anystack</groupId>
<artifactId>nacos-mcp-server</artifactId>
<version>0.0.1-SNAPSHOT</version>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-mcp-registry</artifactId>
<version>1.1.2.2</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
<version>1.1.2</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>这是工程配置,不单独产生控制台输出。验证方法是执行后文的 mvn spring-boot:run;若依赖解析失败,先用 mvn dependency:tree 检查是否被父工程覆盖了上述版本。
定义工具并交给 MCP Server
创建 src/main/java/dev/anystack/mcp/Application.java。@Tool 决定要暴露的方法,MethodToolCallbackProvider 则把这个对象交给 Spring AI MCP Server。
package dev.anystack.mcp;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Service;
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
@Bean
ToolCallbackProvider weatherTools(WeatherService weatherService) {
// 将业务对象的方法元数据交给 MCP Server 暴露。
return MethodToolCallbackProvider.builder()
.toolObjects(weatherService)
.build();
}
@Service
static class WeatherService {
@Tool(description = "Get weather information by city name")
public String getWeather(@ToolParam(description = "City name") String cityName) {
return "Sunny in " + cityName;
}
}
}这段代码依赖后面的 Nacos 与 MCP Server 配置才会形成完整注册流程;单独编译只会得到一个带 Tool 元数据的 Spring Boot 应用。
配置启动即注册
创建 src/main/resources/application.yml。服务名与版本会成为目录中识别 MCP Server 的关键字段,Nacos 地址和凭据用环境变量覆盖,避免把环境信息写死在代码仓库。
server:
port: 8080
spring:
application:
name: mcp-nacos-registry-example
ai:
mcp:
server:
name: weather-mcp
version: 1.0.0
type: SYNC
instructions: "Provides a weather lookup tool"
alibaba:
mcp:
nacos:
server-addr: ${NACOS_ADDR:127.0.0.1:8848}
namespace: ${NACOS_NAMESPACE:public}
username: ${NACOS_USERNAME:}
password: ${NACOS_PASSWORD:}
register:
enabled: trueNacos 的自动注册机制会在 MCP Server 启动后把服务信息纳入统一 MCP 管理,并同步到相关注册与配置能力中。([Nacos 官网][2])

启动并验证注册结果
先确认 Nacos 可访问,再在项目根目录启动应用。若部署开启鉴权,同时设置具有目标 namespace 权限的用户名和密码。
export NACOS_ADDR="127.0.0.1:8848"
export NACOS_NAMESPACE="public"
mvn spring-boot:run预期输出:应用完成启动并持续运行;启动耗时、线程名等动态值会不同。若这里出现 Nacos 连接或 MCP 注册异常,应先解决地址、权限或依赖版本问题,不要继续做目录验证。
... Started Application in <TIME> seconds ...随后用管理 API 精确查询刚注册的服务:
curl -sS -G \
-w '\nHTTP_STATUS:%{http_code}\n' \
"http://$NACOS_ADDR/nacos/v3/admin/ai/mcp/list" \
--data-urlencode "pageNo=1" \
--data-urlencode "pageSize=20" \
--data-urlencode "namespaceId=$NACOS_NAMESPACE" \
--data-urlencode "mcpName=weather-mcp" \
--data-urlencode "search=accurate"预期结果:HTTP 状态为 200,code 为 0,并且 pageItems 中存在名称为 weather-mcp、最新版本为 1.0.0 的条目;ID 和协议由实际运行时生成或推导。
{"code":0,"message":"success","data":{"totalCount":1,"pageNumber":1,"pagesAvailable":1,"pageItems":[{"id":"<ID>","name":"weather-mcp","protocol":"<PROTOCOL>","latestPublishedVersion":"1.0.0"}]}}
HTTP_STATUS:200如果列表中没有条目,按“应用是否真正启动 → register.enabled 是否为 true → Nacos 地址与 namespace 是否一致 → 当前身份是否有权限”的顺序定位。若服务名已存在但启动时报兼容错误,还要检查该名称和版本下已有的协议、服务引用与 Tool 结构是否和当前实例一致;Nacos 会对这些关键信息做兼容性校验。([Nacos 官网][2])