> ## Documentation Index
> Fetch the complete documentation index at: https://javaai.pig4cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 客户端启动器文档

# MCP 客户端启动器文档

Spring AI MCP 客户端启动器 (`spring-ai-mcp-client-boot-starter`) 促进了与符合模型上下文协议 (MCP) 的服务器的集成。

## 概述

MCP 客户端启动器提供：

* 用于与 MCP 服务器交互的自动配置客户端。
* 用于发送 MCP 请求和处理响应的简化抽象。
* 与 Spring Boot 应用程序的无缝集成。

## 入门

要开始使用 MCP 客户端启动器，请将以下依赖项添加到您的 `pom.xml` 文件中：

```xml theme={"system"}
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-client-boot-starter</artifactId>
</dependency>
```

## 配置

MCP 客户端启动器可以通过 `application.properties` 或 `application.yml` 文件进行配置。以下是一些常见的配置选项：

### 客户端属性

* `spring.ai.mcp.client.base-url`: MCP 服务器的基础 URL。
* `spring.ai.mcp.client.timeout`: 请求超时时间 (以毫秒为单位，默认为 10000)。
* `spring.ai.mcp.client.username` / `spring.ai.mcp.client.password`: 用于基本身份验证的凭证 (如果需要)。

示例 `application.properties`：

```properties theme={"system"}
spring.ai.mcp.client.base-url=http://localhost:8080/mcp
spring.ai.mcp.client.username=user
spring.ai.mcp.client.password=secret
```

### ChatModel 和 EmbeddingModel 配置

当使用 MCP 客户端时，您通常会在您的应用程序中定义 `ChatModel` 或 `EmbeddingModel` bean，这些 bean 将通过 MCP 与远程模型进行通信。

通过设置以下属性，将 Spring AI 模型配置为使用 MCP 客户端：

* 对于聊天模型：`spring.ai.mcp.chat.enabled=true`
* 对于嵌入模型：`spring.ai.mcp.embedding.enabled=true`

您还可以使用 `spring.ai.mcp.chat.options.*` 和 `spring.ai.mcp.embedding.options.*` 配置特定于模型的选项，例如模型名称。

示例 `application.properties` 以通过 MCP 使用远程聊天模型：

```properties theme={"system"}
spring.ai.mcp.client.base-url=http://mcp-server.example.com/mcp

spring.ai.mcp.chat.enabled=true
spring.ai.mcp.chat.options.model=remote-gpt-model # 在 MCP 服务器上配置的模型名称
# spring.ai.mcp.chat.options.temperature=0.7 # 其他模型选项
```

## 用法

配置完成后，您可以像使用任何其他 Spring AI 模型一样，将 `ChatModel` 或 `EmbeddingModel` 注入到您的服务中。MCP 客户端启动器确保这些模型通过 MCP 协议与配置的远程服务器进行通信。

### 使用 `ChatModel`

```java theme={"system"}
import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class MyChatService {

    private final ChatClient chatClient; // ChatClient 将使用配置的 MCP ChatModel

    @Autowired
    public MyChatService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    public String getChatResponse(String message) {
        Prompt prompt = new Prompt(message);
        ChatResponse response = chatClient.call(prompt);
        return response.getResult().getOutput().getContent();
    }
}
```

### 使用 `EmbeddingModel`

```java theme={"system"}
import org.springframework.ai.embedding.EmbeddingClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class MyEmbeddingService {

    private final EmbeddingClient embeddingClient; // EmbeddingClient 将使用配置的 MCP EmbeddingModel

    @Autowired
    public MyEmbeddingService(EmbeddingClient embeddingClient) {
        this.embeddingClient = embeddingClient;
    }

    public List<Double> getEmbeddings(String text) {
        return embeddingClient.embed(text);
    }
}
```

## 请求和响应

客户端将自动将您的 `ChatModel` 或 `EmbeddingModel` 调用转换为 MCP 请求，并将 MCP 响应转换回标准的 Spring AI 对象 (`ChatResponse`, `EmbeddingResponse`)。

## 安全性

如果 MCP 服务器需要身份验证，请确保在客户端配置中提供必要的凭证 (例如，用户名/密码进行基本身份验证，或配置 OAuth2/JWT 的 `RestTemplate` 自定义器)。

启动器支持通过 `spring.ai.mcp.client.username` 和 `spring.ai.mcp.client.password` 属性进行基本身份验证。
对于更高级的身份验证方案，您可能需要提供一个自定义的 `RestTemplateBuilderConfigurer` bean 来自定义用于 MCP 通信的 `RestTemplate`。

```java theme={"system"}
@Bean
public RestTemplateBuilderConfigurer mcpRestTemplateBuilderConfigurer() {
    return builder -> builder.additionalInterceptors(
        // 添加您的自定义身份验证拦截器，例如用于 OAuth2 或 API 密钥头的拦截器
        (request, body, execution) -> {
            request.getHeaders().add("X-Custom-Auth-Header", "YourToken");
            return execution.execute(request, body);
        }
    );
}
```

## 故障排除

* **连接错误**：验证 MCP 服务器的 `base-url` 是否正确，以及服务器是否可访问。
* **身份验证失败**：检查您的凭证或身份验证机制是否正确配置。
* **模型未找到**：确保您在客户端选项中指定的模型名称与 MCP 服务器上可用的模型匹配。

有关更多详细信息和高级配置，请参阅 Spring AI MCP [参考文档](https://docs.spring.io/spring-ai/reference/api/mcp.html) 和 [GitHub 仓库](https://github.com/spring-projects/spring-ai/tree/main/spring-ai-spring-boot-starters/spring-ai-mcp-client-spring-boot-starter)。

<Card title="文档有误？请协助编辑" icon="pencil" href="https://github.com/javaai-pig4cloud-com/javaai-docs/edit/main/spring-ai/api/mcp/mcp-client-boot-starter-docs.mdx">
  发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
</Card>