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

# 构建 MCP 客户端

> 开始构建可与所有 MCP 服务器集成的自定义客户端。

在本教程中，你将学习如何构建一个由 LLM 驱动、并能连接 MCP 服务器的聊天机器人客户端。

开始之前，建议先阅读[构建 MCP 服务器](/docs/develop/build-server)教程，这有助于理解客户端和服务器如何通信。

<Tabs>
  <Tab title="Python">
    [这里可以找到本教程的完整代码。](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-python)

    ## 系统要求

    开始前，请确保系统满足以下要求：

    * Mac 或 Windows 电脑。
    * 已安装最新 Python 版本。
    * 已安装最新版本的 `uv`。

    ## 设置环境

    首先使用 `uv` 创建新的 Python 项目：

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      # Create project directory
      uv init mcp-client
      cd mcp-client

      # Create virtual environment
      uv venv

      # Activate virtual environment
      source .venv/bin/activate

      # Install required packages
      uv add mcp anthropic python-dotenv

      # Remove boilerplate files
      rm main.py

      # Create our main file
      touch client.py
      ```

      ```powershell Windows theme={null}
      # Create project directory
      uv init mcp-client
      cd mcp-client

      # Create virtual environment
      uv venv

      # Activate virtual environment
      .venv\Scripts\activate

      # Install required packages
      uv add mcp anthropic python-dotenv

      # Remove boilerplate files
      del main.py

      # Create our main file
      new-item client.py
      ```
    </CodeGroup>

    ## 设置 API Key

    你需要从 [Anthropic Console](https://console.anthropic.com/settings/keys) 获取 Anthropic API key。

    创建 `.env` 文件来保存它：

    ```bash theme={null}
    echo "ANTHROPIC_API_KEY=your-api-key-goes-here" > .env
    ```

    将 `.env` 添加到 `.gitignore`：

    ```bash theme={null}
    echo ".env" >> .gitignore
    ```

    <Warning>
      请确保妥善保护你的 `ANTHROPIC_API_KEY`！
    </Warning>

    ## 创建客户端

    ### 基础客户端结构

    首先设置 imports，并创建基础客户端类：

    ```python theme={null}
    import asyncio
    from typing import Optional
    from contextlib import AsyncExitStack

    from mcp import ClientSession, StdioServerParameters
    from mcp.client.stdio import stdio_client

    from anthropic import Anthropic
    from dotenv import load_dotenv

    load_dotenv()  # load environment variables from .env

    class MCPClient:
        def __init__(self):
            # Initialize session and client objects
            self.session: Optional[ClientSession] = None
            self.exit_stack = AsyncExitStack()
            self.anthropic = Anthropic()
        # methods will go here
    ```

    ### 服务器连接管理

    接下来实现连接 MCP server 的方法：

    ```python theme={null}
    async def connect_to_server(self, server_script_path: str):
        """Connect to an MCP server

        Args:
            server_script_path: Path to the server script (.py or .js)
        """
        is_python = server_script_path.endswith('.py')
        is_js = server_script_path.endswith('.js')
        if not (is_python or is_js):
            raise ValueError("Server script must be a .py or .js file")

        command = "python" if is_python else "node"
        server_params = StdioServerParameters(
            command=command,
            args=[server_script_path],
            env=None
        )

        stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
        self.stdio, self.write = stdio_transport
        self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))

        await self.session.initialize()

        # List available tools
        response = await self.session.list_tools()
        tools = response.tools
        print("\nConnected to server with tools:", [tool.name for tool in tools])
    ```

    ### 查询处理逻辑

    现在添加处理查询和 tool calls 的核心功能：

    ```python theme={null}
    async def process_query(self, query: str) -> str:
        """Process a query using Claude and available tools"""
        messages = [
            {
                "role": "user",
                "content": query
            }
        ]

        response = await self.session.list_tools()
        available_tools = [{
            "name": tool.name,
            "description": tool.description,
            "input_schema": tool.inputSchema
        } for tool in response.tools]

        # Initial Claude API call
        response = self.anthropic.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=1000,
            messages=messages,
            tools=available_tools
        )

        # Process response and handle tool calls
        final_text = []

        assistant_message_content = []
        for content in response.content:
            if content.type == 'text':
                final_text.append(content.text)
                assistant_message_content.append(content)
            elif content.type == 'tool_use':
                tool_name = content.name
                tool_args = content.input

                # Execute tool call
                result = await self.session.call_tool(tool_name, tool_args)
                final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")

                assistant_message_content.append(content)
                messages.append({
                    "role": "assistant",
                    "content": assistant_message_content
                })
                messages.append({
                    "role": "user",
                    "content": [
                        {
                            "type": "tool_result",
                            "tool_use_id": content.id,
                            "content": result.content
                        }
                    ]
                })

                # Get next response from Claude
                response = self.anthropic.messages.create(
                    model="claude-sonnet-4-20250514",
                    max_tokens=1000,
                    messages=messages,
                    tools=available_tools
                )

                final_text.append(response.content[0].text)

        return "\n".join(final_text)
    ```

    ### 交互式聊天界面

    现在添加聊天循环和清理逻辑：

    ```python theme={null}
    async def chat_loop(self):
        """Run an interactive chat loop"""
        print("\nMCP Client Started!")
        print("Type your queries or 'quit' to exit.")

        while True:
            try:
                query = input("\nQuery: ").strip()

                if query.lower() == 'quit':
                    break

                response = await self.process_query(query)
                print("\n" + response)

            except Exception as e:
                print(f"\nError: {str(e)}")

    async def cleanup(self):
        """Clean up resources"""
        await self.exit_stack.aclose()
    ```

    ### 主入口

    最后，添加主执行逻辑：

    ```python theme={null}
    async def main():
        if len(sys.argv) < 2:
            print("Usage: python client.py <path_to_server_script>")
            sys.exit(1)

        client = MCPClient()
        try:
            await client.connect_to_server(sys.argv[1])
            await client.chat_loop()
        finally:
            await client.cleanup()

    if __name__ == "__main__":
        import sys
        asyncio.run(main())
    ```

    完整的 `client.py` 文件见[这里](https://github.com/modelcontextprotocol/quickstart-resources/blob/main/mcp-client-python/client.py)。

    ## 关键组件说明

    ### 1. Client 初始化

    * `MCPClient` 类会初始化 session 管理和 API clients
    * 使用 `AsyncExitStack` 正确管理资源
    * 配置用于 Claude 交互的 Anthropic client

    ### 2. Server 连接

    * 同时支持 Python 和 Node.js servers
    * 校验 server script 类型
    * 设置正确的通信通道
    * 初始化 session 并列出可用 tools

    ### 3. 查询处理

    * 维护对话上下文
    * 处理 Claude 响应和 tool calls
    * 管理 Claude 与 tools 之间的消息流
    * 将结果组合成连贯响应

    ### 4. 交互界面

    * 提供简单命令行界面
    * 处理用户输入并显示响应
    * 包含基础错误处理
    * 支持优雅退出

    ### 5. 资源管理

    * 正确清理资源
    * 处理连接问题
    * 执行优雅关闭流程

    ## 常见自定义点

    1. **Tool 处理**
       * 修改 `process_query()` 以处理特定 tool 类型
       * 为 tool calls 添加自定义错误处理
       * 实现特定 tool 的响应格式化

    2. **响应处理**
       * 自定义 tool results 的格式化方式
       * 添加响应过滤或转换
       * 实现自定义日志

    3. **用户界面**
       * 添加 GUI 或 Web 界面
       * 实现富控制台输出
       * 添加命令历史或自动补全

    ## 运行 Client

    要让 client 连接任意 MCP server：

    ```bash theme={null}
    uv run client.py path/to/server.py # python server
    uv run client.py path/to/build/index.js # node server
    ```

    <Note>
      如果你继续使用 [server quickstart 中的天气教程](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-python)，命令可能类似这样：`python client.py .../quickstart-resources/weather-server-python/weather.py`
    </Note>

    client 将会：

    1. 连接到指定 server
    2. 列出可用 tools
    3. 启动交互式聊天 session，你可以：
       * 输入查询
       * 查看 tool 执行
       * 获取 Claude 的响应

    如果连接到 server quickstart 中的天气 server，效果大致如下：

    <Frame>
      <img src="https://mintcdn.com/mcp-af858c62/jSqzMzM_desZfWyn/images/client-claude-cli-python.png?fit=max&auto=format&n=jSqzMzM_desZfWyn&q=85&s=64abb260c9dea567815e2f86b6733a97" width="1932" height="1739" data-path="images/client-claude-cli-python.png" />
    </Frame>

    ## 工作原理

    提交查询时：

    1. client 从 server 获取可用 tools 列表
    2. 你的查询会连同 tool 描述一起发送给 Claude
    3. Claude 决定使用哪些 tools（如果需要）
    4. client 通过 server 执行任何被请求的 tool calls
    5. 结果发回 Claude
    6. Claude 提供自然语言响应
    7. 响应显示给你

    ## 最佳实践

    1. **错误处理**
       * 始终用 try-catch blocks 包裹 tool calls
       * 提供有意义的错误消息
       * 优雅处理连接问题

    2. **资源管理**
       * 使用 `AsyncExitStack` 正确清理
       * 完成后关闭连接
       * 处理 server 断开连接

    3. **安全**
       * 将 API keys 安全存储在 `.env` 中
       * 校验 server 响应
       * 谨慎处理 tool 权限

    4. **Tool 名称**
       * Tool 名称可以根据[这里](/specification/draft/server/tools#tool-names)指定的格式进行校验
       * 如果 tool 名称符合指定格式，MCP client 不应使其校验失败

    ## 排障

    ### Server 路径问题

    * 仔细检查 server script 路径是否正确
    * 如果相对路径不工作，请使用绝对路径
    * Windows 用户请确保路径中使用正斜杠 (/) 或转义反斜杠 (\\)
    * 确认 server 文件扩展名正确（Python 用 .py，Node.js 用 .js）

    正确路径用法示例：

    ```bash theme={null}
    # Relative path
    uv run client.py ./server/weather.py

    # Absolute path
    uv run client.py /Users/username/projects/mcp-server/weather.py

    # Windows path (either format works)
    uv run client.py C:/projects/mcp-server/weather.py
    uv run client.py C:\\projects\\mcp-server\\weather.py
    ```

    ### 响应时间

    * 第一次响应可能最多需要 30 秒才返回
    * 这是正常现象，期间会发生：
      * server 初始化
      * Claude 处理查询
      * tools 正在执行
    * 后续响应通常更快
    * 在初始等待期间不要中断进程

    ### 常见错误消息

    如果看到：

    * `FileNotFoundError`：检查 server 路径
    * `Connection refused`：确保 server 正在运行且路径正确
    * `Tool execution failed`：确认 tool 所需环境变量已设置
    * `Timeout error`：考虑在 client 配置中增加 timeout
  </Tab>

  <Tab title="TypeScript">
    [本教程完整代码见这里。](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-typescript)

    ## 系统要求

    开始前，请确保系统满足以下要求：

    * Mac 或 Windows 电脑
    * 已安装 Node.js 17 或更高版本
    * 已安装最新版 `npm`
    * Anthropic API key (Claude)

    ## 设置环境

    首先，创建并设置项目：

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      # Create project directory
      mkdir mcp-client-typescript
      cd mcp-client-typescript

      # Initialize npm project
      npm init -y

      # Install dependencies
      npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv

      # Install dev dependencies
      npm install -D @types/node typescript

      # Create source file
      touch index.ts
      ```

      ```powershell Windows theme={null}
      # Create project directory
      md mcp-client-typescript
      cd mcp-client-typescript

      # Initialize npm project
      npm init -y

      # Install dependencies
      npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv

      # Install dev dependencies
      npm install -D @types/node typescript

      # Create source file
      new-item index.ts
      ```
    </CodeGroup>

    更新 `package.json`，设置 `type: "module"` 并添加 build script：

    ```json package.json theme={null}
    {
      "type": "module",
      "scripts": {
        "build": "tsc && chmod 755 build/index.js"
      }
    }
    ```

    在项目根目录创建 `tsconfig.json`：

    ```json tsconfig.json theme={null}
    {
      "compilerOptions": {
        "target": "ES2022",
        "module": "Node16",
        "moduleResolution": "Node16",
        "outDir": "./build",
        "rootDir": "./",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true
      },
      "include": ["index.ts"],
      "exclude": ["node_modules"]
    }
    ```

    ## 设置 API Key

    你需要从 [Anthropic Console](https://console.anthropic.com/settings/keys) 获取 Anthropic API key。

    创建 `.env` 文件来存储它：

    ```bash theme={null}
    echo "ANTHROPIC_API_KEY=<your key here>" > .env
    ```

    将 `.env` 添加到 `.gitignore`：

    ```bash theme={null}
    echo ".env" >> .gitignore
    ```

    <Warning>
      请确保妥善保护 `ANTHROPIC_API_KEY`！
    </Warning>

    ## 创建 Client

    ### 基础 Client 结构

    首先，在 `index.ts` 中设置 imports 并创建基础 client 类：

    ```typescript theme={null}
    import { Anthropic } from "@anthropic-ai/sdk";
    import {
      MessageParam,
      Tool,
    } from "@anthropic-ai/sdk/resources/messages/messages.mjs";
    import { Client } from "@modelcontextprotocol/sdk/client/index.js";
    import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
    import readline from "readline/promises";
    import dotenv from "dotenv";

    dotenv.config();

    const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
    if (!ANTHROPIC_API_KEY) {
      throw new Error("ANTHROPIC_API_KEY is not set");
    }

    class MCPClient {
      private mcp: Client;
      private anthropic: Anthropic;
      private transport: StdioClientTransport | null = null;
      private tools: Tool[] = [];

      constructor() {
        this.anthropic = new Anthropic({
          apiKey: ANTHROPIC_API_KEY,
        });
        this.mcp = new Client({ name: "mcp-client-cli", version: "1.0.0" });
      }
      // methods will go here
    }
    ```

    ### Server 连接管理

    接下来，实现连接 MCP server 的方法：

    ```typescript theme={null}
    async connectToServer(serverScriptPath: string) {
      try {
        const isJs = serverScriptPath.endsWith(".js");
        const isPy = serverScriptPath.endsWith(".py");
        if (!isJs && !isPy) {
          throw new Error("Server script must be a .js or .py file");
        }
        const command = isPy
          ? process.platform === "win32"
            ? "python"
            : "python3"
          : process.execPath;

        this.transport = new StdioClientTransport({
          command,
          args: [serverScriptPath],
        });
        await this.mcp.connect(this.transport);

        const toolsResult = await this.mcp.listTools();
        this.tools = toolsResult.tools.map((tool) => {
          return {
            name: tool.name,
            description: tool.description,
            input_schema: tool.inputSchema,
          };
        });
        console.log(
          "Connected to server with tools:",
          this.tools.map(({ name }) => name)
        );
      } catch (e) {
        console.log("Failed to connect to MCP server: ", e);
        throw e;
      }
    }
    ```

    ### 查询处理逻辑

    现在添加用于处理查询和 tool calls 的核心功能：

    ```typescript theme={null}
    async processQuery(query: string) {
      const messages: MessageParam[] = [
        {
          role: "user",
          content: query,
        },
      ];

      const response = await this.anthropic.messages.create({
        model: "claude-sonnet-4-20250514",
        max_tokens: 1000,
        messages,
        tools: this.tools,
      });

      const finalText = [];

      for (const content of response.content) {
        if (content.type === "text") {
          finalText.push(content.text);
        } else if (content.type === "tool_use") {
          const toolName = content.name;
          const toolArgs = content.input as { [x: string]: unknown } | undefined;

          const result = await this.mcp.callTool({
            name: toolName,
            arguments: toolArgs,
          });
          finalText.push(
            `[Calling tool ${toolName} with args ${JSON.stringify(toolArgs)}]`
          );

          messages.push({
            role: "user",
            content: result.content as string,
          });

          const response = await this.anthropic.messages.create({
            model: "claude-sonnet-4-20250514",
            max_tokens: 1000,
            messages,
          });

          finalText.push(
            response.content[0].type === "text" ? response.content[0].text : ""
          );
        }
      }

      return finalText.join("\n");
    }
    ```

    ### 交互式聊天界面

    现在添加聊天循环和清理功能：

    ```typescript theme={null}
    async chatLoop() {
      const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout,
      });

      try {
        console.log("\nMCP Client Started!");
        console.log("Type your queries or 'quit' to exit.");

        while (true) {
          const message = await rl.question("\nQuery: ");
          if (message.toLowerCase() === "quit") {
            break;
          }
          const response = await this.processQuery(message);
          console.log("\n" + response);
        }
      } finally {
        rl.close();
      }
    }

    async cleanup() {
      await this.mcp.close();
    }
    ```

    ### 主入口

    最后，添加主执行逻辑：

    ```typescript theme={null}
    async function main() {
      if (process.argv.length < 3) {
        console.log("Usage: node index.ts <path_to_server_script>");
        return;
      }
      const mcpClient = new MCPClient();
      try {
        await mcpClient.connectToServer(process.argv[2]);
        await mcpClient.chatLoop();
      } catch (e) {
        console.error("Error:", e);
        await mcpClient.cleanup();
        process.exit(1);
      } finally {
        await mcpClient.cleanup();
        process.exit(0);
      }
    }

    main();
    ```

    ## 运行 Client

    要让 client 连接任意 MCP server：

    ```bash theme={null}
    # Build TypeScript
    npm run build

    # Run the client
    node build/index.js path/to/server.py # python server
    node build/index.js path/to/build/index.js # node server
    ```

    <Note>
      如果你继续使用 [server quickstart 中的天气教程](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-typescript)，命令可能类似这样：`node build/index.js .../quickstart-resources/weather-server-typescript/build/index.js`
    </Note>

    **client 将会：**

    1. 连接到指定 server
    2. 列出可用 tools
    3. 启动交互式聊天 session，你可以：
       * 输入查询
       * 查看 tool 执行
       * 获取 Claude 的响应

    ## 工作原理

    提交查询时：

    1. client 从 server 获取可用 tools 列表
    2. 你的查询会连同 tool 描述一起发送给 Claude
    3. Claude 决定使用哪些 tools（如果需要）
    4. client 通过 server 执行任何被请求的 tool calls
    5. 结果发回 Claude
    6. Claude 提供自然语言响应
    7. 响应显示给你

    ## 最佳实践

    1. **错误处理**
       * 使用 TypeScript 类型系统更好地检测错误
       * 用 try-catch blocks 包裹 tool calls
       * 提供有意义的错误消息
       * 优雅处理连接问题

    2. **安全**
       * 将 API keys 安全存储在 `.env` 中
       * 校验 server 响应
       * 谨慎处理 tool 权限

    ## 排障

    ### Server 路径问题

    * 仔细检查 server script 路径是否正确
    * 如果相对路径不工作，请使用绝对路径
    * Windows 用户请确保路径中使用正斜杠 (/) 或转义反斜杠 (\\)
    * 确认 server 文件扩展名正确（Node.js 用 .js，Python 用 .py）

    正确路径用法示例：

    ```bash theme={null}
    # Relative path
    node build/index.js ./server/build/index.js

    # Absolute path
    node build/index.js /Users/username/projects/mcp-server/build/index.js

    # Windows path (either format works)
    node build/index.js C:/projects/mcp-server/build/index.js
    node build/index.js C:\\projects\\mcp-server\\build\\index.js
    ```

    ### 响应时间

    * 第一次响应可能最多需要 30 秒才返回
    * 这是正常现象，期间会发生：
      * server 初始化
      * Claude 处理查询
      * tools 正在执行
    * 后续响应通常更快
    * 在初始等待期间不要中断进程

    ### 常见错误消息

    如果看到：

    * `Error: Cannot find module`：检查 build 文件夹，并确保 TypeScript 编译成功
    * `Connection refused`：确保 server 正在运行且路径正确
    * `Tool execution failed`：确认 tool 所需环境变量已设置
    * `ANTHROPIC_API_KEY is not set`：检查 `.env` 文件和环境变量
    * `TypeError`：确保 tool 参数使用正确类型
    * `BadRequestError`：确保你有足够额度访问 Anthropic API
  </Tab>

  <Tab title="Java">
    <Note>
      这是一个基于 Spring AI MCP auto-configuration 和 boot starters 的 quickstart demo。
      如需了解如何手动创建同步和异步 MCP Clients，请参考 [Java SDK Client](https://java.sdk.modelcontextprotocol.io/) 文档。
    </Note>

    该示例演示如何构建一个交互式 chatbot，将 Spring AI 的 Model Context Protocol (MCP) 与 [Brave Search MCP Server](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/brave-search) 结合起来。该应用创建了由 Anthropic Claude AI 模型驱动的对话界面，可以通过 Brave Search 执行互联网搜索，从而支持与实时 Web 数据进行自然语言交互。
    [本教程完整代码见这里。](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/web-search/brave-chatbot)

    ## 系统要求

    开始前，请确保系统满足以下要求：

    * Java 17 or higher
    * Maven 3.6+
    * npx package manager
    * Anthropic API key (Claude)
    * Brave Search API key

    ## 设置环境

    1. 安装 npx (Node Package eXecute)：
       首先确保已安装 [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)，然后运行：

       ```bash theme={null}
       npm install -g npx
       ```

    2. 克隆仓库：

       ```bash theme={null}
       git clone https://github.com/spring-projects/spring-ai-examples.git
       cd model-context-protocol/web-search/brave-chatbot
       ```

    3. 设置 API keys：

       ```bash theme={null}
       export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
       export BRAVE_API_KEY='your-brave-api-key-here'
       ```

    4. 构建应用：

       ```bash theme={null}
       ./mvnw clean install
       ```

    5. 使用 Maven 运行应用：
       ```bash theme={null}
       ./mvnw spring-boot:run
       ```

    <Warning>
      请确保妥善保护 `ANTHROPIC_API_KEY` 和 `BRAVE_API_KEY`！
    </Warning>

    ## 工作原理

    该应用通过几个组件将 Spring AI 与 Brave Search MCP server 集成：

    ### MCP Client 配置

    1. pom.xml 中所需依赖：

    ```xml theme={null}
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-mcp-client</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-anthropic</artifactId>
    </dependency>
    ```

    2. Application properties (application.yml)：

    ```yml theme={null}
    spring:
      ai:
        mcp:
          client:
            enabled: true
            name: brave-search-client
            version: 1.0.0
            type: SYNC
            request-timeout: 20s
            stdio:
              root-change-notification: true
              servers-configuration: classpath:/mcp-servers-config.json
            toolcallback:
              enabled: true
        anthropic:
          api-key: ${ANTHROPIC_API_KEY}
    ```

    这会激活 `spring-ai-starter-mcp-client`，并根据提供的 server 配置创建一个或多个 `McpClient`。
    `spring.ai.mcp.client.toolcallback.enabled=true` 属性会启用 tool callback 机制，自动将所有 MCP tools 注册为 Spring AI tools。
    默认情况下它是禁用的。

    3. MCP Server 配置 (`mcp-servers-config.json`)：

    ```json theme={null}
    {
      "mcpServers": {
        "brave-search": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-brave-search"],
          "env": {
            "BRAVE_API_KEY": "<PUT YOUR BRAVE API KEY>"
          }
        }
      }
    }
    ```

    ### Chat 实现

    chatbot 使用集成了 MCP tool 的 Spring AI ChatClient 实现：

    ```java theme={null}
    var chatClient = chatClientBuilder
        .defaultSystem("You are useful assistant, expert in AI and Java.")
        .defaultToolCallbacks((Object[]) mcpToolAdapter.toolCallbacks())
        .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
        .build();
    ```

    关键特性：

    * 使用 Claude AI 模型进行自然语言理解
    * 通过 MCP 集成 Brave Search，获得实时 Web 搜索能力
    * 使用 InMemoryChatMemory 维护对话记忆
    * 作为交互式命令行应用运行

    ### 构建并运行

    ```bash theme={null}
    ./mvnw clean install
    java -jar ./target/ai-mcp-brave-chatbot-0.0.1-SNAPSHOT.jar
    ```

    or

    ```bash theme={null}
    ./mvnw spring-boot:run
    ```

    应用会启动一个交互式聊天 session，你可以在其中提问。当需要从互联网查找信息来回答查询时，chatbot 会使用 Brave Search。

    chatbot 可以：

    * 使用内置知识回答问题
    * 在需要时使用 Brave Search 执行 Web 搜索
    * 记住对话中前面消息的上下文
    * 组合多个来源的信息，提供更全面的回答

    ### 高级配置

    MCP client 支持额外配置选项：

    * 通过 `McpSyncClientCustomizer` 或 `McpAsyncClientCustomizer` 自定义 client
    * 支持多个 clients 和多种 transport 类型：`STDIO` 与 `SSE` (Server-Sent Events)
    * 集成 Spring AI 的 tool 执行框架
    * 自动 client 初始化和生命周期管理

    对于基于 WebFlux 的应用，可以改用 WebFlux starter：

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

    它提供类似功能，但使用基于 WebFlux 的 SSE transport 实现，推荐用于生产部署。
  </Tab>

  <Tab title="Kotlin">
    [本教程完整代码见这里。](https://github.com/modelcontextprotocol/kotlin-sdk/tree/main/samples/kotlin-mcp-client)

    ## 系统要求

    开始前，请确保系统满足以下要求：

    * JDK 11 or higher
    * Anthropic API key (Claude)

    ## 设置环境

    首先，如果尚未安装，请安装 `java` 和 `gradle`。
    你可以从 [official Oracle JDK website](https://www.oracle.com/java/technologies/downloads/) 下载 `java`。
    验证 `java` 安装：

    ```bash theme={null}
    java --version
    ```

    现在创建并设置项目：

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      # Create a new directory for our project
      mkdir kotlin-mcp-client
      cd kotlin-mcp-client

      # Initialize a new kotlin project
      gradle init
      ```

      ```powershell Windows theme={null}
      # Create a new directory for our project
      md kotlin-mcp-client
      cd kotlin-mcp-client
      # Initialize a new kotlin project
      gradle init
      ```
    </CodeGroup>

    运行 `gradle init` 后，选择 **Application** 作为项目类型，选择 **Kotlin** 作为编程语言。

    或者，也可以使用 [IntelliJ IDEA project wizard](https://kotlinlang.org/docs/jvm-get-started.html) 创建 Kotlin 应用。

    创建项目后，用以下内容替换 `build.gradle.kts`：

    ```kotlin build.gradle.kts theme={null}
    // Check latest versions at https://github.com/modelcontextprotocol/kotlin-sdk/releases
    val mcpVersion = "0.9.0"
    val ktorVersion = "3.2.3"
    val anthropicVersion = "2.15.0"
    val slf4jVersion = "2.0.17"

    plugins {
        kotlin("jvm") version "2.3.20"
        id("com.gradleup.shadow") version "8.3.9"
        application
    }

    application {
        mainClass.set("MainKt")
    }

    dependencies {
        implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
        implementation("io.ktor:ktor-client-cio:$ktorVersion")
        implementation("com.anthropic:anthropic-java:$anthropicVersion")
        implementation("org.slf4j:slf4j-simple:$slf4jVersion")
    }
    ```

    验证所有内容已正确设置：

    ```bash theme={null}
    ./gradlew build
    ```

    ## 设置 API key

    你需要从 [Anthropic Console](https://console.anthropic.com/settings/keys) 获取 Anthropic API key。

    设置 API key：

    ```bash theme={null}
    export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
    ```

    <Warning>
      请确保妥善保护 `ANTHROPIC_API_KEY`！
    </Warning>

    ## 创建 Client

    ### 基础 Client 结构

    首先，创建基础 client 类：

    ```kotlin theme={null}
    class MCPClient(apiKey: String) : AutoCloseable {
        private val anthropic = AnthropicOkHttpClient.builder()
            .apiKey(apiKey)
            .build()

      private val mcp: Client = Client(
            clientInfo = Implementation(name = "mcp-client-cli", version = "1.0.0")
      )
        private var serverProcess: Process? = null
        private lateinit var tools: List<ToolUnion>

        // methods will go here

        override fun close() {
            runBlocking {
                mcp.close()
            }
            serverProcess?.destroy()
            anthropic.close()
        }
    }
    ```

    ### Server 连接管理

    接下来，实现连接 MCP server 的方法：

    ```kotlin theme={null}
    suspend fun connectToServer(serverScriptPath: String) {
        val command = buildList {
            when (serverScriptPath.substringAfterLast(".")) {
                "js" -> add("node")
                "py" -> add(if (System.getProperty("os.name").lowercase().contains("win")) "python" else "python3")
                "jar" -> addAll(listOf("java", "-jar"))
                else -> throw IllegalArgumentException("Server script must be a .js, .py or .jar file")
            }
            add(serverScriptPath)
        }

        val process = ProcessBuilder(command).start()
        serverProcess = process

        val transport = StdioClientTransport(
            input = process.inputStream.asSource().buffered(),
            output = process.outputStream.asSink().buffered(),
        )

        mcp.connect(transport)

        val toolsResult = mcp.listTools()
        tools = toolsResult.tools.map { tool ->
            ToolUnion.ofTool(
                Tool.builder()
                    .name(tool.name)
                    .description(tool.description ?: "")
                    .inputSchema(
                        Tool.InputSchema.builder()
                            .type(JsonValue.from(tool.inputSchema.type))
                            .properties(tool.inputSchema.properties?.toJsonValue() ?: EmptyJsonObject.toJsonValue())
                            .putAdditionalProperty("required", JsonValue.from(tool.inputSchema.required))
                            .build(),
                    )
                    .build(),
            )
        }
        println("Connected to server with tools: ${tools.joinToString(", ") { it.tool().get().name() }}")
    }
    ```

    <Accordion title="JsonObject.toJsonValue() helper">
      该 helper 使用 Jackson 将 kotlinx.serialization `JsonObject` 转换为 Anthropic SDK `JsonValue`：

      ```kotlin theme={null}
      private fun JsonObject.toJsonValue(): JsonValue {
          val mapper = ObjectMapper()
          val node = mapper.readTree(this.toString())
          return JsonValue.fromJsonNode(node)
      }
      ```
    </Accordion>

    ### 查询处理逻辑

    现在添加用于处理查询和 tool calls 的核心功能：

    ```kotlin theme={null}
    suspend fun processQuery(query: String): String {
        val messages = mutableListOf(
            MessageParam.builder()
                .role(MessageParam.Role.USER)
                .content(query)
                .build(),
        )

        val response = anthropic.messages().create(
            MessageCreateParams.builder()
                .model("claude-sonnet-4-20250514")
                .maxTokens(1024)
                .messages(messages)
                .tools(tools)
                .build(),
        )

        val finalText = mutableListOf<String>()
        response.content().forEach { content ->
            when {
                content.isText() -> finalText.add(content.text().get().text())

                content.isToolUse() -> {
                    val toolName = content.toolUse().get().name()
                    val toolArgs =
                        content.toolUse().get()._input().convert(object : TypeReference<Map<String, JsonValue>>() {})

                    val result = mcp.callTool(
                        name = toolName,
                        arguments = toolArgs ?: emptyMap(),
                    )
                    finalText.add("[Calling tool $toolName with args $toolArgs]")

                    messages.add(
                        MessageParam.builder()
                            .role(MessageParam.Role.USER)
                            .content(
                                result.content
                                    .filterIsInstance<TextContent>()
                                    .joinToString("\n") { it.text }
                            )
                            .build(),
                    )

                    val aiResponse = anthropic.messages().create(
                        MessageCreateParams.builder()
                            .model("claude-sonnet-4-20250514")
                            .maxTokens(1024)
                            .messages(messages)
                            .build(),
                    )

                    finalText.add(aiResponse.content().first().text().get().text())
                }
            }
        }

        return finalText.joinToString("\n")
    }
    ```

    ### 交互式聊天

    添加聊天循环：

    ```kotlin theme={null}
    suspend fun chatLoop() {
        println("\nMCP Client Started!")
        println("Type your queries or 'quit' to exit.")

        while (true) {
            print("\nQuery: ")
            val message = readlnOrNull() ?: break
            if (message.trim().lowercase() == "quit") break

            try {
                val response = processQuery(message)
                println("\n$response")
            } catch (e: Exception) {
                println("\nError: ${e.message}")
            }
        }
    }
    ```

    ### 主入口

    最后，添加主执行函数：

    ```kotlin theme={null}
    fun main(args: Array<String>) = runBlocking {
        require(args.isNotEmpty()) { "Usage: java -jar <path> <path_to_server_script>" }

        val apiKey = System.getenv("ANTHROPIC_API_KEY")
        require(!apiKey.isNullOrBlank()) { "ANTHROPIC_API_KEY environment variable is not set" }

        val client = MCPClient(apiKey)
        client.use {
            client.connectToServer(args.first())
            client.chatLoop()
        }
    }
    ```

    ## 运行 client

    要让 client 连接任意 MCP server：

    ```bash theme={null}
    ./gradlew build

    # Run the client
    java -jar build/libs/kotlin-mcp-client-0.1.0-all.jar path/to/server.jar # JVM server
    java -jar build/libs/kotlin-mcp-client-0.1.0-all.jar path/to/server.py  # Python server
    java -jar build/libs/kotlin-mcp-client-0.1.0-all.jar path/to/build/index.js # Node server
    ```

    也可以直接使用 Gradle 运行：

    ```bash theme={null}
    ./gradlew run --args="path/to/server.jar"
    ```

    <Note>
      如果你继续使用 server quickstart 中的天气教程，命令可能类似这样：`java -jar build/libs/kotlin-mcp-client-0.1.0-all.jar .../samples/weather-stdio-server/build/libs/weather-stdio-server-0.1.0-all.jar`
    </Note>

    **client 将会：**

    1. 连接到指定 server
    2. 列出可用 tools
    3. 启动交互式聊天 session，你可以：
       * 输入查询
       * 查看 tool 执行
       * 获取 Claude 的响应

    ## 工作原理

    下面是高层 workflow schema：

    ```mermaid theme={null}
    ---
    config:
        theme: neutral
    ---
    sequenceDiagram
        actor User
        participant Client
        participant Claude
        participant MCP_Server as MCP Server
        participant Tools

        User->>Client: 发送查询
        Client<<->>MCP_Server: 获取可用 tools
        Client->>Claude: 携带 tool 描述发送查询
        Claude-->>Client: 决定 tool 执行
        Client->>MCP_Server: 请求 tool 执行
        MCP_Server->>Tools: 执行选中的 tools
        Tools-->>MCP_Server: 返回结果
        MCP_Server-->>Client: 发送结果
        Client->>Claude: 发送 tool 结果
        Claude-->>Client: 提供最终响应
        Client-->>User: 显示响应
    ```

    提交查询时：

    1. client 从 server 获取可用 tools 列表
    2. 你的查询会连同 tool 描述一起发送给 Claude
    3. Claude 决定使用哪些 tools（如果需要）
    4. client 通过 server 执行任何被请求的 tool calls
    5. 结果发回 Claude
    6. Claude 提供自然语言响应
    7. 响应显示给你

    ## 最佳实践

    1. **错误处理**
       * 利用 Kotlin 类型系统显式建模错误
       * 可能出现异常时，用 `try-catch` blocks 包裹外部 tool 和 API calls
       * 提供清晰且有意义的错误消息
       * 优雅处理网络超时和连接问题

    2. **安全**
       * 将 API keys 和 secrets 安全存储在 `local.properties`、环境变量或 secret managers 中
       * 校验所有外部响应，避免意外或不安全的数据使用
       * 使用 tools 时谨慎处理权限和信任边界

    3. **环境**
       * 通过环境变量设置 `ANTHROPIC_API_KEY`，而不是硬编码
       * 本地开发时使用 `.env` 文件，并配合适当 `.gitignore` 规则

    ## 排障

    ### Server 路径问题

    * 仔细检查 server script 路径是否正确
    * 如果相对路径不工作，请使用绝对路径
    * Windows 用户请确保路径中使用正斜杠 (/) 或转义反斜杠 (\\)
    * 确保已安装所需运行时（Java 用 java，Node.js 用 npm，Python 用 uv）
    * 确认 server 文件扩展名正确（Java 用 .jar，Node.js 用 .js，Python 用 .py）

    正确路径用法示例：

    ```bash theme={null}
    # Relative path
    java -jar build/libs/client.jar ./server/build/libs/server.jar

    # Absolute path
    java -jar build/libs/client.jar /Users/username/projects/mcp-server/build/libs/server.jar

    # Windows path (either format works)
    java -jar build/libs/client.jar C:/projects/mcp-server/build/libs/server.jar
    java -jar build/libs/client.jar C:\\projects\\mcp-server\\build\\libs\\server.jar
    ```

    ### 构建问题

    * 使用 `./gradlew build` 或 `./gradlew shadowJar`（不要用 `./gradlew jar`）创建包含所有依赖的 shadow JAR
    * 如果遇到 JDK 版本错误，请确保已安装 JDK 版本匹配或高于 `build.gradle.kts` 中的 `jvmToolchain` 设置

    ### 响应时间

    * 第一次响应可能最多需要 30 秒才返回
    * 这是正常现象，期间会发生：
      * server 初始化
      * Claude 处理查询
      * tools 正在执行
    * 后续响应通常更快
    * 在初始等待期间不要中断进程

    ### 常见错误消息

    如果看到：

    * `Connection refused`：确保 server 正在运行且路径正确
    * `Tool execution failed`：确认 tool 所需环境变量已设置
    * `ANTHROPIC_API_KEY is not set`：检查环境变量
  </Tab>

  <Tab title="C#">
    [You can find the complete code for this tutorial here.](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/QuickstartClient)

    ## 系统要求

    开始前，请确保系统满足以下要求：

    * .NET 8.0 or higher
    * Anthropic API key (Claude)
    * Windows, Linux, or macOS

    ## 设置环境

    首先，创建新的 .NET 项目：

    ```bash theme={null}
    dotnet new console -n QuickstartClient
    cd QuickstartClient
    ```

    然后，将所需依赖添加到项目：

    ```bash theme={null}
    dotnet add package ModelContextProtocol --prerelease
    dotnet add package Anthropic.SDK
    dotnet add package Microsoft.Extensions.Hosting
    dotnet add package Microsoft.Extensions.AI
    ```

    ## 设置 API key

    你需要从 [Anthropic Console](https://console.anthropic.com/settings/keys) 获取 Anthropic API key。

    ```bash theme={null}
    dotnet user-secrets init
    dotnet user-secrets set "ANTHROPIC_API_KEY" "<your key here>"
    ```

    ## 创建 Client

    ### 基础 Client 结构

    首先，在 `Program.cs` 文件中设置基础 client 类：

    ```csharp theme={null}
    using Anthropic.SDK;
    using Microsoft.Extensions.AI;
    using Microsoft.Extensions.Configuration;
    using Microsoft.Extensions.Hosting;
    using ModelContextProtocol.Client;
    using ModelContextProtocol.Protocol.Transport;

    var builder = Host.CreateApplicationBuilder(args);

    builder.Configuration
        .AddEnvironmentVariables()
        .AddUserSecrets<Program>();
    ```

    这会创建一个 .NET console application 的基础结构，能够从 user secrets 读取 API key。

    接下来，设置 MCP Client：

    ```csharp theme={null}
    var (command, arguments) = GetCommandAndArguments(args);

    var clientTransport = new StdioClientTransport(new()
    {
        Name = "Demo Server",
        Command = command,
        Arguments = arguments,
    });

    await using var mcpClient = await McpClient.CreateAsync(clientTransport);

    var tools = await mcpClient.ListToolsAsync();
    foreach (var tool in tools)
    {
        Console.WriteLine($"Connected to server with tools: {tool.Name}");
    }
    ```

    将此函数添加到 `Program.cs` 文件末尾：

    ```csharp theme={null}
    static (string command, string[] arguments) GetCommandAndArguments(string[] args)
    {
        return args switch
        {
            [var script] when script.EndsWith(".py") => ("python", args),
            [var script] when script.EndsWith(".js") => ("node", args),
            [var script] when Directory.Exists(script) || (File.Exists(script) && script.EndsWith(".csproj")) => ("dotnet", ["run", "--project", script, "--no-build"]),
            _ => throw new NotSupportedException("An unsupported server script was provided. Supported scripts are .py, .js, or .csproj")
        };
    }
    ```

    这会创建一个 MCP client，连接到通过命令行参数提供的 server。随后，它会列出已连接 server 中的可用 tools。

    ### 查询处理逻辑

    现在添加用于处理查询和 tool calls 的核心功能：

    ```csharp theme={null}
    using var anthropicClient = new AnthropicClient(new APIAuthentication(builder.Configuration["ANTHROPIC_API_KEY"]))
        .Messages
        .AsBuilder()
        .UseFunctionInvocation()
        .Build();

    var options = new ChatOptions
    {
        MaxOutputTokens = 1000,
        ModelId = "claude-sonnet-4-20250514",
        Tools = [.. tools]
    };

    Console.ForegroundColor = ConsoleColor.Green;
    Console.WriteLine("MCP Client Started!");
    Console.ResetColor();

    PromptForInput();
    while(Console.ReadLine() is string query && !"exit".Equals(query, StringComparison.OrdinalIgnoreCase))
    {
        if (string.IsNullOrWhiteSpace(query))
        {
            PromptForInput();
            continue;
        }

        await foreach (var message in anthropicClient.GetStreamingResponseAsync(query, options))
        {
            Console.Write(message);
        }
        Console.WriteLine();

        PromptForInput();
    }

    static void PromptForInput()
    {
        Console.WriteLine("Enter a command (or 'exit' to quit):");
        Console.ForegroundColor = ConsoleColor.Cyan;
        Console.Write("> ");
        Console.ResetColor();
    }
    ```

    ## 关键组件说明

    ### 1. Client 初始化

    * client 使用 `McpClient.CreateAsync()` 初始化，该方法会设置 transport 类型以及用于运行 server 的命令。

    ### 2. Server 连接

    * 支持 Python、Node.js 和 .NET servers。
    * 使用参数中指定的命令启动 server。
    * 配置使用 stdio 与 server 通信。
    * 初始化 session 和可用 tools。

    ### 3. 查询处理

    * 使用 [Microsoft.Extensions.AI](https://learn.microsoft.com/dotnet/ai/ai-extensions) 作为 chat client。
    * 配置 `IChatClient` 使用自动 tool (function) invocation。
    * client 读取用户输入并发送给 server。
    * server 处理查询并返回响应。
    * 响应展示给用户。

    ## 运行 Client

    要让 client 连接任意 MCP server：

    ```bash theme={null}
    dotnet run -- path/to/server.csproj # dotnet server
    dotnet run -- path/to/server.py # python server
    dotnet run -- path/to/server.js # node server
    ```

    <Note>
      如果你继续使用 server quickstart 中的天气教程，命令可能类似这样：`dotnet run -- path/to/QuickstartWeatherServer`。
    </Note>

    client 将会：

    1. 连接到指定 server
    2. 列出可用 tools
    3. 启动交互式聊天 session，你可以：
       * 输入查询
       * 查看 tool 执行
       * 获取 Claude 的响应
    4. 完成后退出 session

    如果连接到天气 server quickstart，效果大致如下：

    <Frame>
      <img src="https://mintcdn.com/mcp-af858c62/jSqzMzM_desZfWyn/images/quickstart-dotnet-client.png?fit=max&auto=format&n=jSqzMzM_desZfWyn&q=85&s=e7ca71e8dd391236963c88806591a4cc" width="1115" height="666" data-path="images/quickstart-dotnet-client.png" />
    </Frame>
  </Tab>

  <Tab title="Ruby">
    [本教程完整代码见这里。](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-ruby)

    ## 系统要求

    开始前，请确保系统满足以下要求：

    * Mac 或 Windows 电脑
    * 已安装 Ruby 3.2.0 或更高版本（[Anthropic SDK](https://github.com/anthropics/anthropic-sdk-ruby) 要求）
    * Anthropic API key (Claude)

    ## 设置环境

    首先，创建新的 Ruby 项目：

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      # Create project directory
      mkdir mcp-client
      cd mcp-client

      # Create a Gemfile
      bundle init

      # Add required dependencies
      bundle add anthropic base64 dotenv mcp

      # Create our main file
      touch client.rb
      ```

      ```powershell Windows theme={null}
      # Create project directory
      mkdir mcp-client
      cd mcp-client

      # Create a Gemfile
      bundle init

      # Add required dependencies
      bundle add anthropic base64 dotenv mcp

      # Create our main file
      new-item client.rb
      ```
    </CodeGroup>

    ## 设置 API Key

    你需要从 [Anthropic Console](https://console.anthropic.com/settings/keys) 获取 Anthropic API key。

    创建 `.env` 文件来存储它：

    ```bash theme={null}
    echo "ANTHROPIC_API_KEY=your-api-key-goes-here" > .env
    ```

    将 `.env` 添加到 `.gitignore`：

    ```bash theme={null}
    echo ".env" >> .gitignore
    ```

    <Warning>
      请确保妥善保护 `ANTHROPIC_API_KEY`！
    </Warning>

    ## 创建 Client

    ### 基础 Client 结构

    首先，设置 requires 并创建基础 client 类：

    ```ruby theme={null}
    require "anthropic"
    require "dotenv/load"
    require "json"
    require "mcp"

    class MCPClient
      ANTHROPIC_MODEL = "claude-sonnet-4-20250514"

      def initialize
        @mcp_client = nil
        @transport = nil
        @anthropic_client = nil
      end

      # methods will go here
    end
    ```

    ### Server 连接管理

    接下来，实现连接 MCP server 的方法：

    ```ruby theme={null}
    def connect_to_server(server_script_path)
      command = case File.extname(server_script_path)
      when ".rb"
        "ruby"
      when ".py"
        "python3"
      when ".js"
        "node"
      else
        raise ArgumentError, "Server script must be a .rb, .py, or .js file."
      end

      @transport = MCP::Client::Stdio.new(command: command, args: [server_script_path])
      @mcp_client = MCP::Client.new(transport: @transport)
      @mcp_client.connect

      tool_names = @mcp_client.tools.map(&:name)
      puts "\nConnected to server with tools: #{tool_names}"
    end
    ```

    ### 查询处理逻辑

    现在添加用于处理查询和 tool calls 的核心功能：

    ```ruby theme={null}
    private

    def process_query(query)
      messages = [{ role: "user", content: query }]

      available_tools = @mcp_client.tools.map do |tool|
        { name: tool.name, description: tool.description, input_schema: tool.input_schema }
      end

      # Initial Claude API call.
      response = chat(messages, tools: available_tools)

      # Process response and handle tool calls.
      if response.content.any?(Anthropic::Models::ToolUseBlock)
        assistant_content = response.content.filter_map do |content_block|
          case content_block
          when Anthropic::Models::TextBlock
            { type: "text", text: content_block.text }
          when Anthropic::Models::ToolUseBlock
            { type: "tool_use", id: content_block.id, name: content_block.name, input: content_block.input }
          end
        end
        messages << { role: "assistant", content: assistant_content }
      end

      response.content.each_with_object([]) do |content, response_parts|
        case content
        when Anthropic::Models::TextBlock
          response_parts << content.text
        when Anthropic::Models::ToolUseBlock
          # Execute tool call via MCP.
          result = @mcp_client.call_tool(name: content.name, arguments: content.input)
          response_parts << "[Calling tool #{content.name} with args #{content.input.to_json}]"

          tool_result_content = result.dig("result", "content")
          result_text = if tool_result_content.is_a?(Array)
            tool_result_content.filter_map { |content_item| content_item["text"] }.join("\n")
          else
            tool_result_content.to_s
          end

          messages << {
            role: "user",
            content: [{
              type: "tool_result",
              tool_use_id: content.id,
              content: result_text
            }]
          }

          # Get next response from Claude.
          response = chat(messages)

          response.content.each do |content_block|
            response_parts << content_block.text if content_block.is_a?(Anthropic::Models::TextBlock)
          end
        end
      end.join("\n")
    end

    def chat(messages, tools: nil)
      params = { model: ANTHROPIC_MODEL, max_tokens: 1000, messages: messages }
      params[:tools] = tools if tools

      anthropic_client.messages.create(**params)
    end

    def anthropic_client
      @anthropic_client ||= Anthropic::Client.new(api_key: ENV["ANTHROPIC_API_KEY"])
    end
    ```

    ### 交互式聊天界面

    现在添加聊天循环和清理功能：

    ```ruby theme={null}
    def chat_loop
      puts <<~MESSAGE
        MCP Client Started!
        Type your queries or 'quit' to exit.
      MESSAGE

      loop do
        print "\nQuery: "
        line = $stdin.gets
        break if line.nil?

        query = line.chomp.strip
        break if query.downcase == "quit"
        next if query.empty?

        begin
          response = process_query(query)
          puts "\n#{response}"
        rescue => e
          puts "\nError: #{e.message}"
        end
      end
    end

    def cleanup
      @transport&.close
    end
    ```

    ### 主入口

    最后，添加主执行逻辑：

    ```ruby theme={null}
    if ARGV.empty?
      puts "Usage: ruby client.rb <path_to_server_script>"
      exit 1
    end

    client = MCPClient.new

    begin
      client.connect_to_server(ARGV[0])

      api_key = ENV["ANTHROPIC_API_KEY"]
      if api_key.nil? || api_key.empty?
        puts <<~MESSAGE
          No ANTHROPIC_API_KEY found. To query these tools with Claude, set your API key:
            export ANTHROPIC_API_KEY=your-api-key-here
        MESSAGE
        exit
      end

      client.chat_loop
    rescue => e
      puts "Error: #{e.message}"
      exit 1
    ensure
      client.cleanup
    end
    ```

    完整的 `client.rb` 文件见[这里](https://github.com/modelcontextprotocol/quickstart-resources/blob/main/mcp-client-ruby/client.rb)。

    ## 关键组件说明

    ### 1. Client 初始化

    * `MCPClient` 类使用 nil 引用进行延迟设置
    * Anthropic client 通过 `anthropic_client` 方法延迟初始化
    * 使用 `dotenv` 从 `.env` 加载环境变量

    ### 2. Server 连接

    * 支持 Ruby、Python 和 Node.js servers
    * 使用 `File.extname` 判断 server script 类型
    * 使用 `MCP::Client::Stdio` 作为 stdio transport
    * 初始化 MCP client 并列出可用 tools

    ### 3. 查询处理

    * 将 MCP tools 映射为 Anthropic tool 格式（`name`、`description`、`input_schema`）
    * 使用 `Anthropic::Models::TextBlock` 和 `Anthropic::Models::ToolUseBlock` 做模式匹配
    * 在遍历 tool calls 前先构建一次 assistant content
    * 通过 `@mcp_client.call_tool` 执行 tool calls
    * 使用 `chat` helper 方法封装 Anthropic API calls
    * 使用 `result.dig("result", "content")` 提取 tool result content
    * 将 tool results 传回 Claude 以获得最终响应

    ### 4. 交互界面

    * 提供简单命令行界面
    * 处理用户输入并显示响应
    * 跳过空查询
    * 包含基础错误处理

    ### 5. 资源管理

    * 通过 `begin`...`ensure` 正确清理 transport
    * 使用顶层 `rescue` 处理错误
    * server 连接后校验 API key

    ## 运行 Client

    要让 client 连接任意 MCP server：

    ```bash theme={null}
    bundle exec ruby client.rb path/to/server.rb # ruby server
    bundle exec ruby client.rb path/to/server.py # python server
    bundle exec ruby client.rb path/to/build/index.js # node server
    ```

    <Note>
      如果你继续使用 [server quickstart 中的天气教程](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-ruby)，命令可能类似这样：`bundle exec ruby client.rb /path/to/weather-server-ruby/weather.rb`
    </Note>

    client 将会：

    1. 连接到指定 server
    2. 列出可用 tools
    3. 启动交互式聊天 session，你可以：
       * 输入查询
       * 查看 tool 执行
       * 获取 Claude 的响应

    ## 工作原理

    提交查询时：

    1. client 从 server 获取可用 tools 列表
    2. 你的查询会连同 tool 描述一起发送给 Claude
    3. Claude 决定使用哪些 tools（如果需要）
    4. client 通过 server 执行任何被请求的 tool calls
    5. 结果发回 Claude
    6. Claude 提供自然语言响应
    7. 响应显示给你

    ## 最佳实践

    1. **错误处理**
       * 用 `begin`...`rescue` blocks 包裹 tool calls
       * 提供有意义的错误消息
       * 优雅处理连接问题

    2. **资源管理**
       * 完成后始终关闭 transport
       * 使用 `begin`...`ensure` 正确清理
       * 处理 server 断开连接

    3. **安全**
       * 将 API keys 安全存储在 `.env` 中
       * 校验 server 响应
       * 谨慎处理 tool 权限

    4. **Tool 名称**
       * Tool 名称可以根据[这里](/specification/draft/server/tools#tool-names)指定的格式进行校验
       * 如果 tool 名称符合指定格式，MCP client 不应使其校验失败

    ## 排障

    ### Server 路径问题

    * 仔细检查 server script 路径是否正确
    * 如果相对路径不工作，请使用绝对路径
    * Windows 用户请确保路径中使用正斜杠 (/) 或转义反斜杠 (\\)
    * 确认 server 文件扩展名正确（Python 用 .py，Node.js 用 .js，Ruby 用 .rb）

    正确路径用法示例：

    ```bash theme={null}
    # Relative path
    bundle exec ruby client.rb ./server/weather.rb

    # Absolute path
    bundle exec ruby client.rb /Users/username/projects/mcp-server/weather.rb

    # Windows path (either format works)
    bundle exec ruby client.rb C:/projects/mcp-server/weather.rb
    bundle exec ruby client.rb C:\\projects\\mcp-server\\weather.rb
    ```

    ### 响应时间

    * 第一次响应可能最多需要 30 秒才返回
    * 这是正常现象，期间会发生：
      * server 初始化
      * Claude 处理查询
      * tools 正在执行
    * 后续响应通常更快
    * 在初始等待期间不要中断进程

    ### 常见错误消息

    如果看到：

    * `Errno::ENOENT`：检查 server 路径，并确保命令（`ruby`、`python3`、`node`）可用
    * `Connection refused`：确保 server 正在运行且路径正确
    * `Tool execution failed`：确认 tool 所需环境变量已设置
    * `Anthropic::Errors::AuthenticationError`：检查 `.env` 文件中是否有有效的 `ANTHROPIC_API_KEY`
  </Tab>
</Tabs>

## 后续步骤

<CardGroup cols={2}>
  <Card title="示例服务器" icon="grid" href="/examples">
    查看官方 MCP servers 和 implementations 展示列表
  </Card>
</CardGroup>