Building an MCP Server with Spring AI 1.1’s New Annotations

Spring AI 1.1 introduces a new annotation‑based MCP programming model that simplifies server development. The tutorial starts by creating a fresh Spring Boot Java project that targets Java 17.

The <dependency> for spring-ai-mcp-annotations is added to pom.xml along with the Spring AI BOM (version 1.1.0) and other required libraries such as spring-boot-starter-web, Lombok, FastJSON, Jsoup, and Apache Commons.

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-mcp-annotations</artifactId>
</dependency>

The application.yml enables the new annotation scanner and configures a Streamable HTTP MCP server:

spring:
  ai:
    mcp:
      server:
        annotation-scanner:
          enabled: true
        protocol: STREAMABLE
        name: streamable-mcp-server
        version: 1.0.0
        type: SYNC
        instructions: "This streamable server provides real-time notifications"
        resource-change-notification: true
        tool-change-notification: true
        prompt-change-notification: true
        streamable-http:
          mcp-endpoint: /mcp
          keep-alive-interval: 30s
        server:
          port: 8001

The existing Weibo trending service is refactored: the old @Tool annotation is replaced with @McpTool, providing a name and description. The method now returns a JSON string of hot‑search items after fetching and parsing the Weibo API.

@Service
@Slf4j
public class WeiboTrendingDataRequestService {

    @McpTool(name = "get-weibo-trending",
              description = "获取微博热搜榜，包含时事热点、社会现象、娱乐新闻、明星动态及网络热议话题的实时热门中文资讯")
    public String getWeiboTrending() {
        String url = "https://weibo.com/ajax/side/hotSearch";
        try {
            Connection.Response response = Jsoup.connect(url)
                .ignoreContentType(true)
                .timeout(10000)
                .header("referer", "https://weibo.com")
                .method(Connection.Method.GET)
                .execute();
            if (response.statusCode() != 200) {
                log.error("请求微博热搜失败，HTTP状态码: {}", response.statusCode());
                return "微博热搜获取失败，请稍后再试";
            }
            // parse JSON and build result list …
            return JSON.toJSONString(resultList);
        } catch (Exception e) {
            log.error("工具调用异常: {}", e.getMessage(), e);
            return "工具调用失败，请稍后再试";
        }
    }
}

The new MCP annotation package also provides several context parameter types that are automatically injected:

McpSyncRequestContext : synchronous operations, gives access to the original request, server exchange, transport context, logging, progress, sampling, and elicitation methods.

McpAsyncRequestContext : reactive counterpart using Mono‑based return types.

McpTransportContext : lightweight access to transport‑layer details for stateless calls.

@McpProgressToken : marks a method parameter to receive a progress token.

McpMeta : provides metadata of the MCP request, result, and notifications.

These parameters are not part of the generated JSON schema, but they enable richer tool implementations. For example, a dynamic‑schema tool can be written without pre‑defining arguments:

@McpTool(name = "flexible-tool", description = "Process dynamic schema")
public CallToolResult processDynamic(CallToolRequest request) {
    Map<String, Object> args = request.arguments();
    String result = "Processed " + args.size() + " arguments dynamically";
    return CallToolResult.builder()
        .addTextContent(result)
        .build();
}

After rebuilding, the application starts successfully and logs show that the tool registration is automatic—no manual @Bean registration is needed. The server can be queried with Cherry Stdio, confirming that the tool metadata and execution work as expected.

In summary, Spring AI 1.1’s new MCP annotations streamline server creation, provide built‑in context objects for advanced use‑cases, and support dynamic schemas, making AI‑enhanced backend services easier to develop and maintain.