name	description	languages	products	page_type	urlFragment
.NET OpenAI MCP Agent	This is an MCP agent app written in .NET, using OpenAI, with a remote MCP server written in TypeScript.	csharp bicep azdeveloper	azure-openai azure-container-apps azure	sample	openai-mcp-agent-dotnet

.NET OpenAI MCP Agent

This is an MCP agent app written in .NET, using Azure OpenAI, with a remote MCP server written in TypeScript.

Features

This app provides features like:

• The MCP host + MCP client app is written in .NET Blazor.
• The MCP client app connects to a to-do MCP server written in TypeScript.
• Both MCP client and server apps are running on Azure Container Apps (ACA).
• The MCP client app is secured by the built-in auth of ACA.
• The MCP server app is only accessible from the MCP client app.

Prerequisites

• .NET 9 SDK
• Visual Studio Code + C# Dev Kit
• node.js LTS
• Docker Desktop or Podman Desktop
• Azure Subscription

Getting Started

You can now use GitHub Codespaces to run this sample app (takes several minutes to open it)! 👉 .

Get Azure AI Foundry or GitHub Models

• To run this app, you should have either Azure AI Foundry instance or GitHub Models.
• If you use Azure AI Foundry, make sure you have the GPT-5-mini models deployed deployed.
• As a default, the deployed model name is gpt-5-mini.

Get AI Agent App

1. Create a directory for the app.

   # zsh/bash
   mkdir -p openai-mcp-agent-dotnet

   # PowerShell
   New-Item -ItemType Directory -Path openai-mcp-agent-dotnet -Force

2. Initialize azd.

   cd openai-mcp-agent-dotnet
   azd init -t openai-mcp-agent-dotnet

   NOTE: You'll be asked to enter an environment name, which will be the name of your Azure Resource Group.

3. Make sure that your deployed model name is gpt-5-mini. If your deployed model is different, update src/McpTodo.ClientApp/appsettings.json.

   {
     "OpenAI": {
       // Make sure this is the right deployment name.
       "DeploymentName": "gpt-5-mini"
     }
   }

Get MCP Server App

You can choose the MCP server written either in TypeScript or .NET.

TypeScript MCP Server

1. clone the MCP server.

   git clone https://github.com/Azure-Samples/mcp-container-ts.git ./src/McpTodo.ServerApp

.NET MCP Server

1. Run the following command.

   # zsh/bash
   mv ./azure.yaml ./azure.yaml.typescript
   mv ./azure.yaml.dotnet ./azure.yaml

   # PowerShell
   Rename-Item -Path ./azure.yaml -NewName ./azure.yaml.typescript
   Rename-Item -Path ./azure.yaml.dotnet -NewName ./azure.yaml

2. Run the following command.

   azd env set MCP_SERVER_INGRESS_PORT 8080

Run on Azure

1. Check that you have the necessary permissions:

   • Your Azure account must have the Microsoft.Authorization/roleAssignments/write permission, such as Role Based Access Control Administrator, User Access Administrator, or Owner at the subscription level.
   • Your Azure account must also have the Microsoft.Resources/deployments/write permission at the subscription level.

2. Login to Azure.

   azd auth login

3. Deploy apps to Azure.

   azd up

   NOTE:

   1. By default, the MCP client app is protected by the ACA built-in auth feature. You can turn off this feature before running azd up by setting:

      azd env set USE_LOGIN false

   2. During the deployment, you will be asked to enter the Azure Subscription, location and OpenAI connection string. The connection string should be in the format of Endpoint={{AZURE_OPENAI_ENDPOINT}};Key={{AZURE_OPENAI_API_KEY}}. The Azure OpenAI API endpoint should look like https://<location>.api.cognitive.microsoft.com/.

   3. You can add GitHub PAT in the same format above to use GitHub Models like Endpoint=https://models.inference.ai.azure.com;Key={{GITHUB_PAT}}.

4. In the terminal, get the client app URL deployed. It might look like:

   https://mcptodo-clientapp.{{some-random-string}}.{{location}}.azurecontainerapps.io/

5. Navigate to the client app URL, log-in to the app and enter prompts like:

   Give me list of to do.
   Set "meeting at 1pm".
   Give me list of to do.
   Mark #1 as completed.
   Delete #1 from the to-do list.
   

   NOTE: You might not be asked to login, if you've set the USE_LOGIN value to false.

6. Clean up all the resources deployed.

   azd down --force --prune

Run locally

1. Make sure you're in the openai-mcp-agent-dotnet directory.

2. Add Azure OpenAI API Key.

   dotnet user-secrets --project ./src/McpTodo.ClientApp set ConnectionStrings:openai "Endpoint={{AZURE_OPENAI_ENDPOINT}};Key={{AZURE_OPENAI_API_KEY}}"

   NOTE: You can add GitHub PAT in the same format above to use GitHub Models like Endpoint=https://models.inference.ai.azure.com;Key={{GITHUB_PAT}}.

3. To use TypeScript version of the MCP server, install npm packages.

   pushd ./src/McpTodo.ServerApp
   npm install
   popd

   But to use .NET version of the MCP server, skip this step.

4. Install NuGet packages.

   dotnet restore && dotnet build

5. Run the MCP server app either TypeScript server or .NET one.

   # TypeScript MCP server
   cd ./src/McpTodo.ServerApp
   npm start

   # .NET MCP server
   docker run -i --rm -d -p 3000:8080 ghcr.io/microsoft/mcp-dotnet-samples/todo-list:http

6. Run the client app in another terminal.

   dotnet watch run --project ./src/McpTodo.ClientApp

7. Navigate to https://localhost:7256 or http://localhost:5011 and enter prompts like:

   Give me list of to do.
   Set "meeting at 1pm".
   Give me list of to do.
   Mark #1 as completed.
   Delete #1 from the to-do list.
   

8. Type CTRL+C to stop the agent app.

9. Stop the container, if .NET MCP server is running.

   docker stop $(docker ps -q --filter ancestor=ghcr.io/microsoft/mcp-dotnet-samples/todo-list:http)

Run in local containers

1. Make sure that you're running either Docker Desktop or Podman Desktop on your local machine.

2. Make sure you're in the openai-mcp-agent-dotnet directory.

3. Export user secrets to .env.

   # bash/zsh
   dotnet user-secrets list --project src/McpTodo.ClientApp \
       | sed 's/ConnectionStrings:openai/ConnectionStrings__openai/' > .env

   # PowerShell
   (dotnet user-secrets list --project src/McpTodo.ClientApp) `
       -replace "ConnectionStrings:openai", "ConnectionStrings__openai" | Out-File ".env" -Force

4. To use TypeScript version of the MCP server, skip this step. But to use .NET version of the MCP server, run the following command.

   # zsh/bash
   mv ./compose.yaml ./compose.yaml.typescript
   mv ./compose.yaml.dotnet ./compose.yaml

   # PowerShell
   Rename-Item -Path ./compose.yaml -NewName ./compose.yaml.typescript
   Rename-Item -Path ./compose.yaml.dotnet -NewName ./compose.yaml

5. Run both apps in containers.

   docker compose up --build

6. Navigate to http://localhost:8080 and enter prompts like:

   Give me list of to do.
   Set "meeting at 1pm".
   Give me list of to do.
   Mark #1 as completed.
   Delete #1 from the to-do list.
   

7. Type CTRL+C to stop all containers.

8. Delete all running containers.

   docker compose down

Resources

• .NET AI Template
• Model Context Protocol (MCP) C# SDK
• MCP .NET samples
• MCP Todo app in TypeScript