本文为个人学习笔记整理，仅供交流参考，非专业教学资料，内容请自行甄别。

---

前言

  本篇主要介绍MCP协议，以及如何开发MCP协议的服务端，客户端；stdio和sse两种开发模式，MCP的部署方案。

---

一、MCP协议

1.1、概述

  MCP 旨在充当 AI 大模型与外部工具、数据源之间的 “万能插座”，解决 AI 模型与外部资源，如数据库、API、本地文件等的交互碎片化问题，统一通信规范，让不同大模型能够通过统一接口调用各类工具，无需重复适配开发。
  通过MCP协议，可以接入第三方的API，而不需要用户自己再编写工具，是对于工具调用的一种优化。
  主要分为了三个角色：

• MCP Host：是发起请求的 AI 应用程序，如聊天机器人、AI 驱动的 IDE、Claude Desktop 等，主要职责是接收用户输入，与大模型交互生成指令，并在大模型需要调用外部工具时触发 MCP 流程。
• MCP Client：作为 MCP Host 与 MCP Server 之间的桥梁，负责与 MCP Server 建立持久连接，将大模型的请求翻译为 MCP 标准格式并发送给 MCP Server，同时接收 MCP Server 的响应并返回给 MCP Host。
• MCP Server：是提供特定功能的外部程序，能够连接各种数据源，如 Google Drive、Slack、GitHub、数据库和 Web 浏览器等，主要职责是提供标准化接口和工具类，支持访问本地或远程资源，执行具体的工具调用，并返回结果。

  目前有一些主流的MCP应用市场，如mcp.so，或阿里云百炼平台。

1.2、MCP架构

  MCP由两层组成:

• 数据层：定义基于 JSON-RPC 的客户端-服务器通信协议,包括生命周期管理以及核心原语,例如工具、资源、提示和通知。
• 传输层：定义实现客户端与服务器之间数据交换的通信机制和通道,包括传输专用的连接设置、消息框接和授权。

  数据层实现了基于JSON-RPC 2.0的交换协议,该协议定义了消息结构和语义。 此层包括:

• Lifecycle management生命周期管理：处理客户端与服务器之间的连接初始化、通信和连接终止
• Server features服务器功能：使服务器能够提供核心功能,包括用于人工智能操作的工具、上下文数据资源,以及客户端之间交互模板的提示
• Client features客户端功能：允许服务器向客户端请求从主机 LLM 进行采样、从用户中获取输入,并向客户端记录消息
• Utility features实用功能：支持用于远程操作的实时更新通知和进度跟踪等附加功能

  传输层管理客户端与服务器之间的通信通道和身份验证。它负责连接建立、消息框接以及MCP参与者之间的安全通信。
  MCP支持两种传输机制:

• Stdio传输：使用标准输入/输出流,在同一设备上实现本地进程之间的直接过程通信,提供最佳性能,且无网络开销。
• SSE传输：使用 HTTP POST 用于客户端到服务器的消息,并可选使用服务器发送事件以实现流媒体功能。此传输支持远程服务器通信,并支持标准的HTTP身份验证方法,包括无记名令牌、API密钥和自定义报头。

二、使用MCP

  以在IDEA中使用Amap Maps（高德地图MCP）为例，采用的是stdio的本地方式，首先需要在项目中引入依赖：

<!--        mcp服务-->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
            <version>1.0.0-M6</version>
        </dependency>

  然后在resources目录下增加配置文件mcp-servers.json，官方提供了一个默认的配置，但是我在windows下实际操作是不可行的，包括网上教程说的在windows下要将npx改成npx.cmd

  如果引入官方的配置，项目启动不了，可以尝试以下命令，在IDEA的终端中依次执行，我这里采用的node版本是22.14.0，镜像源是官方：

# 1、全局安装
npm install -g @amap/amap-maps-mcp-server
# 2、查看全局npm包的安装路径
npm config get prefix
# 3、查找启动类
cd 第二步的结果\node_modules\@amap\amap-maps-mcp-server
# 4、在包目录下，查看 package.json 中的 "main" 或 "bin" 字段
Get-Content package.json | Select-String -Pattern '"main"|"\bin"'

{
  "mcpServers": {
    "amap-maps": {
      "command": "node",
      "args": [
        "第三步的结果\\第四步的结果",
        "--api-key",
        "换成你自己的apikey"
      ],
      "env": {
        "AMAP_MAPS_API_KEY": "换成你自己的apikey"
      }
    }
  }
}

  还需要在application.yml中加入：

spring:
  ai:
    mcp:
      client:
        stdio:
          servers-configuration: classpath:mcp-servers.json

  然后在应用中注入：

    @Resource
    private ToolCallbackProvider toolCallbackProvider;

    /**
     * 测试mcp
     * @param message
     * @param chatId
     * @return
     */
    public String doChatWithMcp(String message, String chatId) {
        ChatResponse response = chatClient
                .prompt()
                .user(message)
                .advisors(spec -> spec.param(CHAT_MEMORY_CONVERSATION_ID_KEY, chatId)
                        .param(CHAT_MEMORY_RETRIEVE_SIZE_KEY, 10))
                .tools(toolCallbackProvider)
                .call()
                .chatResponse();
        String content = response.getResult().getOutput().getText();
        return content;
    }

  启动项目，在自定义的日志拦截器中打上断点观察，发现已经加入了MCP提供的工具。

三、MCP客户端和服务端开发

3.1、MCP服务端开发

  MCP的服务端开发，有两种形式，第一是stdio本地模式，和sse远程模式，首先我们新建一个项目，在进行MCP开发时，建议按照单一职责原则，一个类型的MCP应用，单独放在一个项目中。在创建项目后，需要引入依赖：

        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-mcp-server-webmvc-spring-boot-starter</artifactId>
            <version>1.0.0-M6</version>
        </dependency>

3.1.1、stdio模式

  首先编写配置文件：

spring:
  ai:
    mcp:
      server:
        name: image-search-mcp-server
        version: 1848
        type: SYNC
        # stdio
        stdio: true
  # stdio
  main:
    web-application-type: none
    banner-mode: off

  然后进行工具编写，这里的工具是根据的教程，使用了pexels搜图API，工具开发的流程和上一篇提到的相同，同样是注解模式，使用@Tool和@ToolParam进行标记：

@Service
public class ImageSearchTool {

    // 替换为你的 Pexels API 密钥（需从官网申请）
    private static final String API_KEY = "换成你自己的";

    // Pexels 常规搜索接口（请以文档为准）
    private static final String API_URL = "https://api.pexels.com/v1/search";

    @Tool(description = "search image from web")
    public String searchImage(@ToolParam(description = "Search query keyword") String query) {
        try {
            return String.join(",", searchMediumImages(query));
        } catch (Exception e) {
            return "Error search image: " + e.getMessage();
        }
    }

    /**
     * 搜索中等尺寸的图片列表
     *
     * @param query
     * @return
     */
    public List<String> searchMediumImages(String query) {
        // 设置请求头（包含API密钥）
        Map<String, String> headers = new HashMap<>();
        headers.put("Authorization", API_KEY);

        // 设置请求参数（仅包含query，可根据文档补充page、per_page等参数）
        Map<String, Object> params = new HashMap<>();
        params.put("query", query);

        // 发送 GET 请求
        String response = HttpUtil.createGet(API_URL)
                .addHeaders(headers)
                .form(params)
                .execute()
                .body();

        // 解析响应JSON（假设响应结构包含"photos"数组，每个元素包含"medium"字段）
        return JSONUtil.parseObj(response)
                .getJSONArray("photos")
                .stream()
                .map(photoObj -> (JSONObject) photoObj)
                .map(photoObj -> photoObj.getJSONObject("src"))
                .map(photo -> photo.getStr("medium"))
                .filter(StrUtil::isNotBlank)
                .collect(Collectors.toList());
    }
}

  最后需要在配置类中注册Bean，加入自定义的工具，这里直接加在了启动类中，因为Spring Boot的启动类本身就可以作为配置类，@SpringBootApplication复合注解包含了@Configuration。

@SpringBootApplication
public class ImageSearchMcpServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(ImageSearchMcpServerApplication.class, args);
    }


    @Bean
    public ToolCallbackProvider imageSearchTools(ImageSearchTool imageSearchTool){
        return MethodToolCallbackProvider.builder().toolObjects(imageSearchTool).build();
    }
}

  在stdio模式下，还需要将整个应用打包成jar包：

---

  上述的是stdio模式，服务端的开发，在客户端，同样需要在json配置文件中加入服务端的信息，这里的env，可以向服务端传递一些环境参数，服务端可以采用System.env获取。

{
  "mcpServers": {
    "image-search-mcp-server": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
        "image-search-mcp-server/target/image-search-mcp-server-0.0.1-SNAPSHOT.jar"
      ],
      "env": {}
    }
  }
}

  然后客户端就可以启动项目，流程和二、使用MCP中的类似。

3.1.2、sse模式

  服务端采用sse远程模式，则需要编写配置文件：

spring:
  ai:
    mcp:
      server:
        name: image-search-mcp-server
        version: 1848
        type: SYNC
        # sse
        stdio: false

  工具的编写和注册和本地模式相同，sse模式不用打jar包，而是需要启动项目。注意端口和客户端的不能冲突。

---

  客户端则需要修改配置：

spring:
  ai:
    mcp:
      client:
        sse:
          connections:
            server1:
              url: http://localhost:8081

  然后启动项目进行测试。

四、MCP远程部署

  MCP服务，除了可以部署在自己的服务器上，还可以托管在第三方的云平台上，比如阿里云百炼平台-MCP
  根据官方文档，首先进入管理页面，点击右上角的创建MCP服务：

  使用默认的方式即可：

  这里的安装方式，官方只提供了三种：

• npx是基于js语法开发的MCP服务的部署
• uvx是基于python开发的MCP服务的部署
• sse是基于java的，但是需要本地启动服务。

  为了演示该功能，采用npx的模式，进行设置，然后提交部署：


  选择自定义的MCP