• 教程
• 文档
• 人工智能

本篇指南以 mcp-for-beginners 开源课程「02-client」章节为核心，系统讲解 Model Context Protocol（MCP）客户端的编写全过程：如何选择并导入 SDK、如何实例化传输与客户端、如何列出并调用服务器上的工具、资源与提示词，以及如何在 TypeScript、Python、.NET、Java、Rust 五种语言中完成从连接到运行。读完本文，你将能够独立编写一个可用的 MCP 客户端，并把它接入自己的宿主应用。

1. 客户端在 MCP 生态中的角色

MCP（Model Context Protocol）采用客户端—服务器架构。客户端（Client）是自定义应用或脚本，它直接与 MCP 服务器通信，请求服务器暴露的资源（Resources）、工具（Tools）和提示词（Prompts）。

与上一章节介绍的 Inspector 这类图形化调试工具不同，编写自己的客户端意味着以编程方式、自动化地与服务器交互。这使得开发者能够：

• 把 MCP 能力集成进自己的工作流；
• 自动化执行重复任务；
• 针对特定需求构建定制化解决方案。

本章学习目标

完成本章后，你将能够：

• 理解一个客户端能做什么；
• 独立编写自己的客户端；
• 将客户端与 MCP 服务器连接并测试，确认服务器按预期工作。

2. 编写客户端前的四个准备步骤

在动手写代码前，需要明确客户端编写过程中必然涉及的四件事：

1. 导入正确的库：使用与服务器相同的 SDK，但引入的是客户端一侧的构造（constructs）。
2. 实例化客户端：创建客户端实例，并将其连接到选定的传输方式（transport）。
3. 决定列出哪些资源：MCP 服务器自带资源、工具和提示词，你需要决定客户端要列举其中哪些。
4. 集成到宿主应用：一旦得知服务器的能力清单，需要把它接入宿主应用——当用户输入提示词或下达其他命令时，触发对应的服务器功能。

一个先睹为快的完整示例（TypeScript）

下面的代码是客户端最简形态的完整演示，先建立整体印象，后续小节再逐步拆解：

import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; const transport = new StdioClientTransport({ command: "node", args: ["server.js"] }); const client = new Client( { name: "example-client", version: "1.0.0" } ); await client.connect(transport); // 列出提示词 const prompts = await client.listPrompts(); // 获取提示词 const prompt = await client.getPrompt({ name: "example-prompt", arguments: { arg1: "value" } }); // 列出资源 const resources = await client.listResources(); // 读取资源 const resource = await client.readResource({ uri: "file:///example.txt" }); // 调用工具 const result = await client.callTool({ name: "example-tool", arguments: { arg1: "value" } });

这段代码完成了三件事：导入库、创建客户端实例并通过 stdio 建立连接、列出提示词/资源/工具并逐一调用。这就是一个能够与 MCP 服务器对话的最小客户端。

3. 练习：五步编写一个完整客户端

下面按照「导入库 → 实例化 → 列能力 → 调功能 → 运行」五个步骤逐段讲解，五种语言并行对照，可以边读边跟着敲代码。

3.1 第 1 步：导入正确的库

编写客户端需要两类引用：客户端本身与选定的传输协议。本章以stdio为主——它面向「在本机运行」的进程，适合本地开发调试；**SSE（Server-Sent Events）**是另一种基于 HTTP 的传输选项，会在后续章节展开，但本章先聚焦 stdio。

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

Python

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

.NET

using Microsoft.Extensions.AI; using Microsoft.Extensions.Configuration; using Microsoft.Extensions.Hosting; using ModelContextProtocol.Client;

Java

Java 客户端要连接上一章 Getting Started with MCP Server 中构建的服务器。沿用相同的 Java Spring Boot 项目结构，新建名为SDKClient的类，放在src/main/java/com/microsoft/mcp/sample/client/目录下，加入以下导入：

import java.util.Map; import org.springframework.web.reactive.function.client.WebClient; import io.modelcontextprotocol.client.McpClient; import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport; import io.modelcontextprotocol.spec.McpClientTransport; import io.modelcontextprotocol.spec.McpSchema.CallToolRequest; import io.modelcontextprotocol.spec.McpSchema.CallToolResult; import io.modelcontextprotocol.spec.McpSchema.ListToolsResult;

Rust

首先在Cargo.toml中添加依赖：

[package] name = "calculator-client" version = "0.1.0" edition = "2024" [dependencies] rmcp = { version = "0.5.0", features = ["client", "transport-child-process"] } serde_json = "1.0.141" tokio = { version = "1.46.1", features = ["rt-multi-thread"] }

随后在客户端代码中导入所需库：

use rmcp::{ RmcpError, model::CallToolRequestParam, service::ServiceExt, transport::{ConfigureCommandExt, TokioChildProcess}, }; use tokio::process::Command;

其中rmcpcrate 通过client特性启用客户端能力，transport-child-process提供子进程传输；TokioChildProcess配合tokio::process::Command负责拉起并连接服务器进程。

3.2 第 2 步：创建客户端与传输实例

TypeScript

const transport = new StdioClientTransport({ command: "node", args: ["server.js"] }); const client = new Client( { name: "example-client", version: "1.0.0" } ); await client.connect(transport);

这里有三处关键点：

• 创建 stdio 传输实例——注意command与args指定了如何定位并启动服务器，这是编写客户端时必需的一步：

  const transport = new StdioClientTransport({ command: "node", args: ["server.js"] });

• 实例化客户端——通过名称与版本号声明客户端身份：

  const client = new Client( { name: "example-client", version: "1.0.0" });

• 建立连接——把客户端绑定到选定的传输：

  await client.connect(transport);

仓库中的完整实现 solution/typescript/src/client.ts 在实例化后依次执行了listPrompts()、getPrompt()、listResources()、listResourceTemplates()与callTool()，是本章 TS 部分可运行的参考样板；其 package.json 中声明了@modelcontextprotocol/sdk: ">=1.26.0"、zod、typescript等依赖。

Python

from mcp import ClientSession, StdioServerParameters, types from mcp.client.stdio import stdio_client # 创建 stdio 连接用的服务器参数 server_params = StdioServerParameters( command="mcp", # 可执行文件 args=["run", "server.py"], # 可选命令行参数 env=None, # 可选环境变量 ) async def run(): async with stdio_client(server_params) as (read, write): async with ClientSession( read, write ) as session: # 初始化连接 await session.initialize() if __name__ == "__main__": import asyncio asyncio.run(run())

要点拆解：

• 导入所需库；
• 实例化StdioServerParameters对象——用它来启动服务器，使客户端能够连接；
• 定义run方法，内部调用stdio_client启动客户端会话；
• 创建入口点，把run交给asyncio.run。

.NET

using Microsoft.Extensions.AI; using Microsoft.Extensions.Configuration; using Microsoft.Extensions.Hosting; using ModelContextProtocol.Client; var builder = Host.CreateApplicationBuilder(args); builder.Configuration .AddEnvironmentVariables() .AddUserSecrets<Program>(); var clientTransport = new StdioClientTransport(new() { Name = "Demo Server", Command = "dotnet", Arguments = ["run", "--project", "path/to/file.csproj"], }); await using var mcpClient = await McpClient.CreateAsync(clientTransport);

注意：Arguments中既可以指向*.csproj项目文件，也可以直接指向可执行文件。仓库中 solution/dotnet/Program.cs 将Command指向编译好的server可执行文件（Arguments = []），随后调用ListToolsAsync()与CallToolAsync()，展示了 .NET 侧的完整闭环。

Java

public class SDKClient { public static void main(String[] args) { var transport = new WebFluxSseClientTransport(WebClient.builder().baseUrl("http://localhost:8080")); new SDKClient(transport).run(); } private final McpClientTransport transport; public SDKClient(McpClientTransport transport) { this.transport = transport; } public void run() { var client = McpClient.sync(this.transport).build(); client.initialize(); // 你的客户端逻辑写在这里 } }

要点拆解：

• 主方法配置了SSE 传输，指向http://localhost:8080——即 MCP 服务器运行的地址；
• 客户端类把传输作为构造器参数接收；
• 在run方法中，用传输构建同步 MCP 客户端并初始化连接；
• SSE 传输适用于与 Java Spring Boot MCP 服务器进行 HTTP 通信。

仓库中的完整实现 solution/java/.../SDKClient.java 在此基础上还调用了ping()校验连接，并在收尾调用closeGracefully()优雅关闭。

Rust

Rust 客户端假定服务器是同一目录下的同级项目calculator-server（仓库 solution/rust 中的版本则假定同级项目名为server）。下面的代码会启动服务器并与之连接：

async fn main() -> Result<(), RmcpError> { // 假定服务器是同一目录下名为 "calculator-server" 的同级项目 let server_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")) .parent() .expect("failed to locate workspace root") .join("calculator-server"); let client = () .serve( TokioChildProcess::new(Command::new("cargo").configure(|cmd| { cmd.arg("run").current_dir(server_dir); })) .map_err(RmcpError::transport_creation::<TokioChildProcess>)?, ) .await?; // TODO: 初始化 // TODO: 列出工具 // TODO: 调用 add 工具，参数 = {"a": 3, "b": 2} client.cancel().await?; Ok(()) }

其中().serve(...)以单元类型作为「零依赖客户端」占位，通过TokioChildProcess在指定目录执行cargo run拉起服务器；client.cancel()负责结束会话。

3.3 第 3 步：列出服务器的能力

连接已建立，但客户端目前还不知道服务器提供什么。接下来进行能力列举：

TypeScript

// 列出提示词 const prompts = await client.listPrompts(); // 列出资源 const resources = await client.listResources(); // 列出工具 const tools = await client.listTools();

Python

# 列出可用资源 resources = await session.list_resources() print("LISTING RESOURCES") for resource in resources: print("Resource: ", resource) # 列出可用工具 tools = await session.list_tools() print("LISTING TOOLS") for tool in tools.tools: print("Tool: ", tool.name)

这里通过list_resources()列出可用资源，通过list_tools()列出工具，并逐条打印。

.NET

foreach (var tool in await client.ListToolsAsync()) { Console.WriteLine($"{tool.Name} ({tool.Description})"); }

以上示例展示了如何列出服务器上的工具，并为每个工具打印名称。

Java

// 列出并演示工具 ListToolsResult toolsList = client.listTools(); System.out.println("Available Tools = " + toolsList); // 也可以 ping 服务器以验证连接 client.ping();

要点：

• 调用listTools()获取 MCP 服务器上所有可用工具；
• 使用ping()验证与服务器的连接是否正常；
• ListToolsResult包含所有工具的信息，包括名称、描述和输入模式（input schema）。

Rust

在主函数中，初始化客户端后即可初始化服务器并列出其部分能力：

// 初始化 let server_info = client.peer_info(); println!("Server info: {:?}", server_info); // 列出工具 let tools = client.list_tools(Default::default()).await?; println!("Available tools: {:?}", tools);

仓库 solution/rust/src/main.rs 对这一步做了增强：通过peer_info()打印服务器名称、版本、协议版本与各项能力开关（tools/resources/prompts/completions/logging），再遍历list_tools结果输出每个工具的名称与描述——这是「能力发现」环节在生产级代码中的典型形态。

至此能力清单已齐备。但本章的客户端是「简单」客户端——它不会自主决策，只有在我们显式调用时才会触发功能；下一章会构建拥有自身大语言模型（LLM）的高级客户端。现在先看如何调用服务器功能。

3.4 第 4 步：调用功能

调用功能的关键是传对参数，某些场景还需要指定目标名称。

TypeScript

// 读取资源 const resource = await client.readResource({ uri: "file:///example.txt" }); // 调用工具 const result = await client.callTool({ name: "example-tool", arguments: { arg1: "value" } }); // 调用提示词 const promptResult = await client.getPrompt({ name: "review-code", arguments: { code: "console.log(\"Hello world\")" } })

• 读取资源：通过readResource()并指定uri调用。服务器端对应的实现大概是这样：

  server.resource( "readFile", new ResourceTemplate("file://{name}", { list: undefined }), async (uri, { name }) => ({ contents: [{ uri: uri.href, text: `Hello, ${name}!` }] }) );

  客户端传入的file://example.txt与服务器的file://{name}模板匹配，example.txt会被映射到占位符name。

• 调用工具：指定工具的name与arguments：

  const result = await client.callTool({ name: "example-tool", arguments: { arg1: "value" } });

• 获取提示词：调用getPrompt()并传入name与arguments。服务器端声明如下：

  server.prompt( "review-code", { code: z.string() }, ({ code }) => ({ messages: [{ role: "user", content: { type: "text", text: `Please review this code:\n\n${code}` } }] }) );

  客户端代码与服务器声明一一对应：

  const promptResult = await client.getPrompt({ name: "review-code", arguments: { code: "console.log(\"Hello world\")" } })

Python

# 读取资源 print("READING RESOURCE") content, mime_type = await session.read_resource("greeting://hello") # 调用工具 print("CALL TOOL") result = await session.call_tool("add", arguments={"a": 1, "b": 7}) print(result.content)

这里调用了名为greeting的资源（read_resource），并调用名为add的工具（call_tool）。

.NET

1. 加入调用工具的代码：

var result = await mcpClient.CallToolAsync( "Add", new Dictionary<string, object?>() { ["a"] = 1, ["b"] = 3 }, cancellationToken:CancellationToken.None);

2. 打印结果的代码：

Console.WriteLine(result.Content.First(c => c.Type == "text").Text); // Sum 4

Java

// 调用各种计算器工具 CallToolResult resultAdd = client.callTool(new CallToolRequest("add", Map.of("a", 5.0, "b", 3.0))); System.out.println("Add Result = " + resultAdd); CallToolResult resultSubtract = client.callTool(new CallToolRequest("subtract", Map.of("a", 10.0, "b", 4.0))); System.out.println("Subtract Result = " + resultSubtract); CallToolResult resultMultiply = client.callTool(new CallToolRequest("multiply", Map.of("a", 6.0, "b", 7.0))); System.out.println("Multiply Result = " + resultMultiply); CallToolResult resultDivide = client.callTool(new CallToolRequest("divide", Map.of("a", 20.0, "b", 4.0))); System.out.println("Divide Result = " + resultDivide); CallToolResult resultHelp = client.callTool(new CallToolRequest("help", Map.of())); System.out.println("Help = " + resultHelp);

要点：

• 用callTool()方法配合CallToolRequest对象调用多个计算器工具；
• 每次调用指定工具名称和该工具所需的Map参数；
• 服务器工具期望特定的参数名（例如数学运算使用"a"、"b"）；
• 结果以CallToolResult对象返回，包含服务器响应。

仓库中的 SDKClient.java 还额外演示了power、squareRoot、absolute等扩展工具调用——只要服务器声明了这些工具，客户端就能以相同模式调用。

Rust

// 调用 add 工具，参数 = {"a": 3, "b": 2} let a = 3; let b = 2; let tool_result = client .call_tool(CallToolRequestParam { name: "add".into(), arguments: serde_json::json!({ "a": a, "b": b }).as_object().cloned(), }) .await?; println!("Result of {:?} + {:?}: {:?}", a, b, tool_result);

3.5 第 5 步：运行客户端

在终端执行以下命令启动客户端：

TypeScript

在package.json的"scripts"段添加如下条目：

"client": "tsc && node build/client.js"

npm run client

仓库 solution/typescript/package.json 中同时保留了build、client、inspector三个脚本，其中inspector借助npx @modelcontextprotocol/inspector将服务器挂到官方调试器上，便于对照验证。

Python

python client.py

.NET

dotnet run

Java

先确保 MCP 服务器运行在http://localhost:8080，再启动客户端：

# 构建项目 ./mvnw clean compile # 运行客户端 ./mvnw exec:java -Dexec.mainClass="com.microsoft.mcp.sample.client.SDKClient"

也可以直接运行 solution 目录中提供的完整客户端项目03-GettingStarted/02-client/solution/java：

# 进入解决方案目录 cd 03-GettingStarted/02-client/solution/java # 构建并运行 JAR ./mvnw clean package java -jar target/calculator-client-0.0.1-SNAPSHOT.jar

Rust

cargo fmt cargo run

4. 理解传输层：stdio 与 SSE 的取舍

本章所有语言的示例都围绕两种传输展开，理解二者的差异有助于选型：

• stdio（标准输入/输出）：客户端以子进程方式启动服务器，通过进程的标准输入输出流交换 JSON-RPC 消息。适合「本机运行、随客户端启动」的场景——正如本章 TypeScript、Python、.NET 与 Rust 示例所示，command/args参数直接描述了如何拉起服务器进程。这也是与 01-first-server 章节 中 stdio 服务器天然对接的传输。
• SSE（Server-Sent Events）：基于 HTTP 的单向事件流传输，客户端通过 URL 连接一个已经运行的服务器。Java 示例中的WebFluxSseClientTransport指向http://localhost:8080，正适合 Java Spring Boot 服务器。关键区别在于：stdio 客户端「自己拉起服务器」，而 SSE 客户端连接「已在运行的服务器」。

值得强调的是，客户端既可像本章这样启动服务器的同时自身启动，也可以连接已经运行的服务器——这一灵活性让客户端成为验证服务器能力的绝佳手段，与上一章提到的 Inspector 互为补充。

5. 动手任务：用给定的 Demo 服务器练手

现在用学到的知识构建你自己的客户端。下面是可供调用的服务器代码，试着调用它，并尝试为服务器添加更多功能使其更有趣。

TypeScript 服务器

import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; // 创建 MCP 服务器 const server = new McpServer({ name: "Demo", version: "1.0.0" }); // 添加加法工具 server.tool("add", { a: z.number(), b: z.number() }, async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }] }) ); // 添加动态问候资源 server.resource( "greeting", new ResourceTemplate("greeting://{name}", { list: undefined }), async (uri, { name }) => ({ contents: [{ uri: uri.href, text: `Hello, ${name}!` }] }) ); // 开始在 stdin 接收消息、在 stdout 发送消息 async function main() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("MCPServer started on stdin/stdout"); } main().catch((error) => { console.error("Fatal error: ", error); process.exit(1); });

Python 服务器

# server.py from mcp.server.fastmcp import FastMCP # 创建 MCP 服务器 mcp = FastMCP("Demo") # 添加加法工具 @mcp.tool() def add(a: int, b: int) -> int: """Add two numbers""" return a + b # 添加动态问候资源 @mcp.resource("greeting://{name}") def get_greeting(name: str) -> str: """Get a personalized greeting""" return f"Hello, {name}!"

仓库 solution/python/server.py 与上述代码一致；对应的 solution/python/client.py 演示了list_resources()→list_tools()→read_resource("greeting://hello")→call_tool("add", ...)的完整调用链，可直接对照学习。

.NET 服务器

using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; using ModelContextProtocol.Server; using System.ComponentModel; var builder = Host.CreateApplicationBuilder(args); builder.Logging.AddConsole(consoleLogOptions => { // 将所有日志配置到 stderr consoleLogOptions.LogToStandardErrorThreshold = LogLevel.Trace; }); builder.Services .AddMcpServer() .WithStdioServerTransport() .WithToolsFromAssembly(); await builder.Build().RunAsync(); [McpServerToolType] public static class CalculatorTool { [McpServerTool, Description("Adds two numbers")] public static string Add(int a, int b) => $"Sum {a + b}"; }

可以研究 solution/server 中的 .NET 服务器项目，了解如何添加提示词与资源（参考官方 csharp-sdk 的 EverythingServer 示例，以及ModelContextProtocol/Client命名空间下提示词与资源的调用方式）。

Rust

在 上一节 中你已经学会了用 Rust 创建简单 MCP 服务器，可以在此基础上继续扩展，或参考官方 rust-sdk 的 servers 示例。

6. 解决方案与完整示例：仓库中可直接运行的代码

解决方案目录结构

solution 文件夹包含完整的、开箱即用的客户端实现，覆盖本教程的全部概念。每个解决方案都同时包含客户端与服务器代码，按语言组织为独立自包含的项目：

solution/ ├── typescript/ # TypeScript 客户端（npm/Node.js 环境） │ ├── package.json # 依赖与脚本 │ ├── tsconfig.json # TypeScript 配置 │ └── src/ # 源代码 ├── java/ # Java Spring Boot 客户端项目 │ ├── pom.xml # Maven 配置 │ ├── src/ # Java 源文件 │ └── mvnw # Maven wrapper ├── python/ # Python 客户端实现 │ ├── client.py # 主要客户端代码 │ ├── server.py # 配套服务器 │ └── README.md # Python 专属说明 ├── dotnet/ # .NET 客户端项目 │ ├── dotnet.csproj # 项目配置 │ ├── Program.cs # 主要客户端代码 │ └── dotnet.sln # 解决方案文件 ├── rust/ # Rust 客户端实现 │ ├── Cargo.lock # Cargo 锁文件 │ ├── Cargo.toml # 项目配置与依赖 │ ├── src # 源代码 │ │ └── main.rs # 主要客户端代码 └── server/ # 附加 .NET 服务器实现 ├── Program.cs # 服务器代码 └── server.csproj # 服务器项目文件

每个语言的解决方案都提供：包含教程全部特性的完整客户端实现、带正确依赖与配置的可用项目结构、便于快速上手的构建与运行脚本、语言专属的详细 README，以及错误处理与结果处理示例。

使用步骤：

1. 进入首选语言目录：

   cd solution/typescript/ # TypeScript cd solution/java/ # Java cd solution/python/ # Python cd solution/dotnet/ # .NET

2. 按照各目录 README 指引完成依赖安装、项目构建与客户端运行。

3. 预期输出示例：

   Prompt: Please review this code: console.log("hello"); Resource template: file Tool result: { content: [ { type: 'text', text: '9' } ] }

完整的逐步文档见 📖 Solution 文档。

完整单文件示例

除 solution 项目外，本仓库还在03-GettingStarted/02-client/目录提供了五种语言的单文件完整示例，可作为参考实现或项目起点：

例如 client_example_typescript.ts 除连接与列举外，还实现了 add/subtract/multiply/divide/help 五种计算器调用、资源与提示词的读取，以及extractTextResult结果抽取与双重错误处理；client_example_rust.rs 则展示了peer_info信息打印、list_tools与call_tool的完整流程。

每个完整示例都包含：连接建立与错误处理、服务器发现（工具、资源、提示词，视适用性而定）、计算器操作（加、减、乘、除、帮助）、结果处理与格式化输出、全面的错误处理，以及带逐步注释的清晰代码。

上手方式：从上方表格选择语言 → 通读完整示例文件理解整体实现 → 按 complete_examples.md 中的指引运行 → 针对你的具体场景修改扩展。

Solution 项目 vs 完整示例

两种方式都很有价值——需要完整项目时用solution 文件夹，需要学习与参考时用完整示例。

7. 关键要点

本章关于 MCP 客户端的核心结论：

• 客户端既可发现也可调用服务器上的功能；
• 客户端可以在自身启动的同时拉起服务器（如本章做法），也可以连接已运行的服务器；
• 相比 Inspector 等替代方案，客户端是测试服务器能力的绝佳方式（Inspector 见上一章节）。

8. 延伸学习：示例与下一步

仓库内的计算器示例

• Java 计算器
• .NET 计算器
• JavaScript 计算器
• TypeScript 计算器
• Python 计算器
• Rust 计算器

下一步

• 进阶阅读：创建带 LLM 的客户端——本章的客户端需要显式调用功能，而下一步将构建接入自有大语言模型的智能客户端，由 LLM 自主决定调用哪些服务器能力。

本章内容覆盖了从「客户端是什么」到「五种语言完整实现」的全部路径：掌握 stdio/SSE 传输差异、理解能力发现与调用的 API 对应关系、复用 solution 与单文件示例，你就具备了把任意 MCP 服务器接入自身应用的完整能力。

• 教程
• 文档
• 人工智能