Table of Contents

MCP servers do not have to be local stdio processes. If you want a tool surface that can run as a normal HTTP service, scale like an app, and be reachable from a separate client, Streamable HTTP is the practical transport to look at.

Terminology note: current MCP specs call this transport Streamable HTTP. It replaced the older HTTP+SSE transport, but it can still use Server-Sent Events (SSE) when the server streams messages back to the client.

We will build a small MCP server in C# with the official MCP .NET SDK, run it locally, containerize it, deploy it to Azure Container Apps, and call it from a C# client.

Repository: MCP Server on Azure Container Apps with C# and .NET

The sample exposes three tools:

  • echo: returns a message
  • add: adds two integers
  • server_time: returns the server time for a supplied time zone

The sample is intentionally small. It does not try to become a production agent platform. It gets you from zero to a deployed MCP endpoint, with enough structure that you can replace the demo tools with your own application logic.

Prerequisites

You need:

  • .NET 10 SDK
  • Docker
  • Azure CLI
  • An Azure subscription
  • Optional: Node.js if you want to test with the MCP Inspector

The project uses:

  • ModelContextProtocol.AspNetCore for the server
  • ModelContextProtocol for the client
  • Streamable HTTP transport
  • Azure Container Apps for hosting

Project structure

The repository is split into a server, a client, and a small test project:

McpAzureContainerAppsDemo/
  McpAzureContainerAppsDemo.slnx
  Directory.Build.props
  Directory.Packages.props
  src/
    McpAzureContainerAppsDemo.Server/
      Program.cs
      Dockerfile
      Configuration/
      Security/
      Services/
      Tools/
    McpAzureContainerAppsDemo.Client/
      Program.cs
      Configuration/
      Rendering/
  tests/
    McpAzureContainerAppsDemo.Server.Tests/

The MCP-specific code stays small. Most of the actual behavior lives in normal C# services.

That is the pattern I prefer for demos like this: keep the protocol wiring thin and put the business logic somewhere testable.

Create the projects

Start with a solution, a web project for the server, a console project for the client, and an xUnit test project:

mkdir McpAzureContainerAppsDemo
cd McpAzureContainerAppsDemo

dotnet new sln -n McpAzureContainerAppsDemo

mkdir -p src tests
dotnet new web -n McpAzureContainerAppsDemo.Server -o src/McpAzureContainerAppsDemo.Server --framework net10.0
dotnet new console -n McpAzureContainerAppsDemo.Client -o src/McpAzureContainerAppsDemo.Client --framework net10.0
dotnet new xunit -n McpAzureContainerAppsDemo.Server.Tests -o tests/McpAzureContainerAppsDemo.Server.Tests --framework net10.0

Add the projects to the solution:

dotnet sln add \
  src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj \
  src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj \
  tests/McpAzureContainerAppsDemo.Server.Tests/McpAzureContainerAppsDemo.Server.Tests.csproj

Then add the MCP packages:

dotnet add src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj package ModelContextProtocol.AspNetCore
dotnet add src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj package ModelContextProtocol
dotnet add tests/McpAzureContainerAppsDemo.Server.Tests/McpAzureContainerAppsDemo.Server.Tests.csproj reference src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj

If you cloned the repository, you can skip this setup. The packages are already referenced centrally in Directory.Packages.props.

Register the MCP server

The server is a regular ASP.NET Core app.

In Program.cs, the MCP server is added to the service collection, configured with Streamable HTTP, and mapped to /mcp:

builder.Services
    .AddMcpServer(options =>
    {
        options.ServerInfo = new()
        {
            Name = "mcp-azure-container-apps-demo",
            Version = "1.0.0"
        };
    })
    .WithHttpTransport(options => options.Stateless = true)
    .WithToolsFromAssembly();

app.MapMcp("/mcp");

The useful detail is WithToolsFromAssembly().

Instead of manually registering every tool, the SDK discovers tool classes and methods through attributes. That keeps the server startup small and moves tool definitions into their own files.

The sample also adds two regular HTTP endpoints:

app.MapGet("/", (IOptions<McpServerSettings> options) => Results.Ok(new
{
    service = options.Value.Name,
    mcpEndpoint = "/mcp",
    health = "/health"
}));

app.MapGet("/health", () => Results.Ok(new
{
    status = "ok",
    utc = TimeProvider.System.GetUtcNow()
}));

/health is useful for Container Apps health checks and basic smoke testing.

Add tools with attributes

The tools live in Tools/DemoTools.cs.

The class is marked with [McpServerToolType], and each exposed method is marked with [McpServerTool]:

[McpServerToolType]
public sealed class DemoTools(
    CalculatorService calculator,
    ServerTimeService serverTime,
    ILogger<DemoTools> logger)
{
    [McpServerTool(Name = "echo", ReadOnly = true, Idempotent = true)]
    [Description("Returns the message supplied by the caller.")]
    public string Echo(string message)
    {
        logger.LogInformation("Echo tool invoked.");
        return message;
    }

    [McpServerTool(Name = "add", ReadOnly = true, Idempotent = true)]
    [Description("Adds two 32-bit integers and returns the sum.")]
    public int Add(int left, int right) =>
        calculator.Add(left, right);
}

Tool methods can still call normal injected services.

For example, the add tool does not do arithmetic directly in the tool method. It calls a CalculatorService:

public sealed class CalculatorService
{
    public int Add(int left, int right) => checked(left + right);
}

That makes the behavior easy to test without going through MCP at all.

For the server_time tool, the service uses TimeProvider so tests can supply a fixed clock:

public sealed class ServerTimeService(TimeProvider timeProvider, ILogger<ServerTimeService> logger)
{
    public ServerTimeResult GetTime(string? timeZoneId)
    {
        string resolvedTimeZoneId = string.IsNullOrWhiteSpace(timeZoneId)
            ? "UTC"
            : timeZoneId;

        TimeZoneInfo timeZone = TimeZoneInfo.FindSystemTimeZoneById(resolvedTimeZoneId);
        DateTimeOffset utcNow = timeProvider.GetUtcNow();
        DateTimeOffset localTime = TimeZoneInfo.ConvertTime(utcNow, timeZone);

        logger.LogDebug("Resolved server time for timezone {TimeZoneId}.", timeZone.Id);
        return new(timeZone.Id, utcNow, localTime);
    }
}

This is a useful split: tools are the integration layer, services are the behavior.

Run the server locally

Start the server:

dotnet run --project src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj --launch-profile http

The sample listens on:

http://localhost:8080

Check the health endpoint:

curl http://localhost:8080/health

You should get a small JSON response with status and utc.

Call the MCP server from C#

The client uses the same MCP SDK, but with the client package.

The transport is configured for Streamable HTTP:

var transportOptions = new HttpClientTransportOptions
{
    Name = "mcp-azure-container-apps-demo-client",
    Endpoint = settings.ServerUrl,
    TransportMode = HttpTransportMode.StreamableHttp,
    AdditionalHeaders = settings.CreateHeaders()
};

await using var transport = new HttpClientTransport(transportOptions, loggerFactory);
await using McpClient client = await McpClient.CreateAsync(transport, loggerFactory: loggerFactory);

Then the client lists available tools and calls two of them:

IList<McpClientTool> tools = await client.ListToolsAsync();

CallToolResult addResult = await client.CallToolAsync(
    "add",
    new Dictionary<string, object?>
    {
        ["left"] = 40,
        ["right"] = 2
    });

Run it against the local server:

dotnet run --project src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj -- \
  --url http://localhost:8080/mcp \
  --time-zone Europe/Berlin

You should see the tool list, the result of add, and a structured result from server_time.

Add simple API-key protection

For a public HTTP endpoint, even a demo should not leave the MCP endpoint completely open by accident.

This sample uses a very small API-key middleware. It protects /mcp when McpServer__ApiKey is configured and leaves /health unauthenticated:

private static bool RequiresApiKey(PathString path, string? configuredApiKey) =>
    path.StartsWithSegments("/mcp", StringComparison.OrdinalIgnoreCase)
    && !string.IsNullOrWhiteSpace(configuredApiKey);

Run the server with a local key:

McpServer__ApiKey=local-dev-key \
dotnet run --project src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj --launch-profile http

Then pass the same key to the client:

dotnet run --project src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj -- \
  --url http://localhost:8080/mcp \
  --api-key local-dev-key

The client sends the key as an X-Api-Key header.

For production, I would not stop here. I would look at Microsoft Entra ID, managed identity, stricter network boundaries, logging, and proper secret management. For a minimal deployable sample, an environment-driven key keeps the flow understandable.

Inspect with MCP Inspector

You can also test the server with the MCP Inspector:

npx @modelcontextprotocol/inspector

Use Streamable HTTP and connect to:

http://localhost:8080/mcp

If API-key protection is enabled, add this header:

X-Api-Key: local-dev-key

This is useful when you want to inspect the tool schema without writing client code first.

Containerize the server

The Dockerfile uses a normal multi-stage .NET build:

One repo-specific detail: the sample repository uses Directory.Build.props and Directory.Packages.props. If you followed the manual dotnet new steps and kept package versions in the project files, remove COPY Directory.Build.props Directory.Packages.props ./ from the Dockerfile. Do not replace those files with empty placeholders, because MSBuild expects valid XML.

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src

COPY Directory.Build.props Directory.Packages.props ./
COPY src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj src/McpAzureContainerAppsDemo.Server/
RUN dotnet restore src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj

COPY src/McpAzureContainerAppsDemo.Server/ src/McpAzureContainerAppsDemo.Server/
RUN dotnet publish src/McpAzureContainerAppsDemo.Server/McpAzureContainerAppsDemo.Server.csproj \
    --configuration Release \
    --no-restore \
    --output /app/publish

FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
ENV ASPNETCORE_URLS=http://0.0.0.0:8080
EXPOSE 8080
USER $APP_UID
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "McpAzureContainerAppsDemo.Server.dll"]

Build the image from the repository root:

docker build -f src/McpAzureContainerAppsDemo.Server/Dockerfile -t mcp-aca-demo .

Run it locally:

docker run --rm -p 8080:8080 mcp-aca-demo

Or run it with API-key protection:

docker run --rm -p 8080:8080 \
  -e McpServer__ApiKey=local-dev-key \
  mcp-aca-demo

At this point, the server is a containerized ASP.NET Core app exposing /mcp.

That is why Azure Container Apps fits this kind of demo. You do not need a special hosting model for MCP. You can deploy a regular container and let the platform handle ingress, revisions, scaling, and environment variables.

Deploy to Azure Container Apps

Login and set a few variables:

az login

export RESOURCE_GROUP=mcp-aca-demo-rg
export LOCATION=westeurope
export APP_NAME=mcp-aca-demo-$RANDOM
export ENVIRONMENT_NAME=mcp-aca-demo-env
export MCP_API_KEY="$(openssl rand -base64 32)"

If this is the first time your subscription uses these services, register the required resource providers:

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights
az provider register --namespace Microsoft.ContainerRegistry

Wait until Azure Container Registry is registered:

az provider show \
  --namespace Microsoft.ContainerRegistry \
  --query registrationState \
  --output tsv

Continue when the command prints:

Registered

Create the resource group:

az group create \
  --name "$RESOURCE_GROUP" \
  --location "$LOCATION"

Deploy from local source:

# This builds the image and creates an Azure Container Registry (ACR)
# in the resource group if one is needed.
az containerapp up \
  --name "$APP_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --location "$LOCATION" \
  --environment "$ENVIRONMENT_NAME" \
  --source . \
  --ingress external \
  --target-port 8080 \
  --env-vars McpServer__ApiKey="$MCP_API_KEY"

The settings that matter here are:

  • --source .: build and deploy from the local repository
  • --ingress external: expose the app publicly
  • --target-port 8080: match the port used by the container
  • --env-vars McpServer__ApiKey=...: pass the API key into the app configuration

Get the public URL:

export MCP_FQDN="$(az containerapp show \
  --name "$APP_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --query properties.configuration.ingress.fqdn \
  --output tsv)"

echo "https://$MCP_FQDN/mcp"

Then call the deployed MCP server:

dotnet run --project src/McpAzureContainerAppsDemo.Client/McpAzureContainerAppsDemo.Client.csproj -- \
  --url "https://$MCP_FQDN/mcp" \
  --api-key "$MCP_API_KEY" \
  --time-zone Europe/Berlin

If everything is wired correctly, the client behaves the same way as it did locally. It lists tools, calls add, and calls server_time.

That is the practical value of this setup: once the MCP server is exposed over Streamable HTTP, the local and deployed client flow look almost identical.

Cleanup

When you are done, remove the resource group:

az group delete \
  --name "$RESOURCE_GROUP" \
  --yes \
  --no-wait

What I would change for a real system

This repository is a demo. I would change a few things before using the same shape in production.

First, I would replace the static API key with a stronger authentication and authorization model. MCP is a tool boundary. If a tool can read or mutate real data, access control matters.

Second, I would add proper observability. At minimum, I would want logs around tool calls, failures, request IDs, latency, and downstream dependencies. For real operations, OpenTelemetry and the Aspire dashboard are useful places to start.

Third, I would make the tool contract boring and explicit. Clear names, narrow parameters, validation, and predictable errors matter more than clever tool descriptions.

Fourth, I would add integration tests around the HTTP surface. Unit tests are enough for the arithmetic and time services, but the /mcp endpoint, headers, and deployment configuration need their own checks once the sample grows.

Takeaway

You can build and deploy a remote MCP server in .NET without much ceremony.

The flow is:

  1. Create a normal ASP.NET Core app.
  2. Add ModelContextProtocol.AspNetCore.
  3. Register MCP with Streamable HTTP.
  4. Expose tools with attributes.
  5. Keep tool behavior in regular services.
  6. Containerize the server.
  7. Deploy it to Azure Container Apps.
  8. Call it from a C# MCP client.

The add tool is just there to prove the path works. The useful part is the hosting model.

Once MCP runs as a regular HTTP service, it fits naturally into the same deployment path many .NET teams already use: container image, environment variables, ingress, health endpoint, and a small client that points at /mcp.

Use this shape when you need a remote MCP tool service that behaves like a normal .NET web app and can be called from clients outside the host machine.

Do not use the sample as-is when tools can access production data, mutate state, or need user-level authorization. Add real authentication, tighter network boundaries, observability, and integration tests first.

Further reading