Skip to content

Commit b7d09e7

Browse files
alexwolfmsftgewarren
alexwolfmsft
and
gewarren
authored
New mcp client quickstart (#46450)
* New mcp client quickstart --------- Co-authored-by: Genevieve Warren <[email protected]>
1 parent d004a71 commit b7d09e7

File tree

5 files changed

+166
-0
lines changed

5 files changed

+166
-0
lines changed

‎docs/ai/quickstarts/build-mcp-client.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Quickstart - Create a minimal MCP client using .NET
3+
description: Learn to create a minimal MCP client and connect it to an MCP server using .NET
4+
ms.date: 05/27/2025
5+
ms.topic: quickstart
6+
ms.custom: devx-track-dotnet, devx-track-dotnet-ai
7+
author: alexwolfmsft
8+
---
9+
10+
# Create a minimal MCP client using .NET
11+
12+
In this quickstart, you build a minimal [Model Context Protocol (MCP)](../get-started-mcp.md) client using the [C# SDK for MCP](https://github.com/modelcontextprotocol/csharp-sdk). You also learn how to configure the client to connect to an MCP server, such as the one created in the [Build a minimal MCP server](build-mcp-server.md) quickstart.
13+
14+
## Prerequisites
15+
16+
- [.NET 8.0 SDK or higher](https://dotnet.microsoft.com/download)
17+
- [Visual Studio Code](https://code.visualstudio.com/)
18+
19+
> [!NOTE]
20+
> The MCP client you build in the sections ahead connects to the sample MCP server from the [Build a minimal MCP server](build-mcp-server.md) quickstart. You can also use your own MCP server if you provide your own connection configuration.
21+
22+
## Create the .NET host app
23+
24+
Complete the following steps to create a .NET console app. The app acts as a host for an MCP client that connects to an MCP server.
25+
26+
### Create the project
27+
28+
1. In a terminal window, navigate to the directory where you want to create your app, and create a new console app with the `dotnet new` command:
29+
30+
```console
31+
dotnet new console -n MCPHostApp
32+
```
33+
34+
1. Navigate into the newly created project folder:
35+
36+
```console
37+
cd MCPHostApp
38+
```
39+
40+
1. Run the following commands to add the necessary NuGet packages:
41+
42+
```console
43+
dotnet add package Azure.AI.OpenAI --prerelease
44+
dotnet add package Azure.Identity
45+
dotnet add package Microsoft.Extensions.AI
46+
dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
47+
dotnet add package ModelContextProtocol --prerelease
48+
```
49+
50+
1. Open the project folder in your editor of choice, such as Visual Studio Code:
51+
52+
```console
53+
code .
54+
```
55+
56+
### Add the app code
57+
58+
Replace the contents of `Program.cs` with the following code:
59+
60+
:::code language="csharp" source="snippets/mcp-client/program.cs" :::
61+
62+
The preceding code accomplishes the following tasks:
63+
64+
- Initializes an `IChatClient` abstraction using the [`Microsoft.Extensions.AI`](/dotnet/ai/microsoft-extensions-ai) libraries.
65+
- Creates an MCP client and configures it to connect to your MCP server.
66+
- Retrieves and displays a list of available tools from the MCP server, which is a standard MCP function.
67+
- Implements a conversational loop that processes user prompts and utilizes the tools for responses.
68+
69+
## Run and test the app
70+
71+
Complete the following steps to test your .NET host app:
72+
73+
1. In a terminal window open to the root of your project, run the following command to start the app:
74+
75+
```console
76+
dotnet run
77+
```
78+
79+
1. Once the app is running, enter a prompt to run the **ReverseEcho** tool:
80+
81+
```console
82+
Reverse the following: "Hello, minimal MCP server!"
83+
```
84+
85+
1. Verify that the server responds with the echoed message:
86+
87+
```output
88+
!revres PCM laminim ,olleH
89+
```
90+
91+
## Related content
92+
93+
[Get started with .NET AI and the Model Context Protocol](../get-started-mcp.md)

‎docs/ai/quickstarts/build-mcp-server.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,4 +110,5 @@ Configure GitHub Copilot for Visual Studio Code to use your custom MCP server:
110110

111111
## Related content
112112

113+
[Build a minimal MCP client](build-mcp-client.md)
113114
[Get started with .NET AI and the Model Context Protocol](../get-started-mcp.md)

‎docs/ai/quickstarts/snippets/mcp-client/MinimalMCPClient.csproj

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net9.0</TargetFramework>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<Nullable>enable</Nullable>
8+
</PropertyGroup>
9+
10+
<ItemGroup>
11+
<PackageReference Include="Azure.AI.OpenAI" Version="2.2.0-beta.4" />
12+
<PackageReference Include="Azure.Identity" Version="1.13.2" />
13+
<PackageReference Include="Microsoft.Extensions.AI" Version="9.5.0" />
14+
<PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.4.3-preview.1.25230.7" />
15+
<PackageReference Include="ModelContextProtocol" Version="0.1.0-preview.11" />
16+
</ItemGroup>
17+
18+
</Project>

‎docs/ai/quickstarts/snippets/mcp-client/Program.cs

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
using Azure.AI.OpenAI;
2+
using Azure.Identity;
3+
using Microsoft.Extensions.AI;
4+
using ModelContextProtocol.Client;
5+
using ModelContextProtocol.Protocol.Transport;
6+
7+
// Create an IChatClient using Azure OpenAI.
8+
IChatClient client =
9+
new ChatClientBuilder(
10+
new AzureOpenAIClient(new Uri("<your-azure-openai-endpoint>"),
11+
new DefaultAzureCredential())
12+
.GetChatClient("gpt-4o").AsIChatClient())
13+
.UseFunctionInvocation()
14+
.Build();
15+
16+
// Create the MCP client
17+
// Configure it to start and connect to your MCP server.
18+
var mcpClient = await McpClientFactory.CreateAsync(
19+
new StdioClientTransport(new()
20+
{
21+
Command = "dotnet run",
22+
Arguments = ["--project", "<path-to-your-mcp-server-project>"],
23+
Name = "Minimal MCP Server",
24+
}));
25+
26+
// List all available tools from the MCP server.
27+
Console.WriteLine("Available tools:");
28+
var tools = await mcpClient.ListToolsAsync();
29+
foreach (var tool in tools)
30+
{
31+
Console.WriteLine($"{tool}");
32+
}
33+
Console.WriteLine();
34+
35+
// Conversational loop that can utilize the tools via prompts.
36+
List<ChatMessage> messages = [];
37+
while (true)
38+
{
39+
Console.Write("Prompt: ");
40+
messages.Add(new(ChatRole.User, Console.ReadLine()));
41+
42+
List<ChatResponseUpdate> updates = [];
43+
await foreach (var update in client
44+
.GetStreamingResponseAsync(messages, new() { Tools = [.. tools] }))
45+
{
46+
Console.Write(update);
47+
updates.Add(update);
48+
}
49+
Console.WriteLine();
50+
51+
messages.AddMessages(updates);
52+
}

‎docs/ai/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ items:
3535
href: quickstarts/ai-templates.md
3636
- name: Build a minimal MCP server
3737
href: quickstarts/build-mcp-server.md
38+
- name: Build a minimal MCP client
39+
href: quickstarts/build-mcp-client.md
3840
- name: Concepts
3941
items:
4042
- name: How generative AI and LLMs work

0 commit comments

Comments
 (0)