DotnetFastMCP

DotnetFastMCP - Enterprise-Grade Model Context Protocol Server Framework

[](https://dotnet.microsoft.com) [](https://www.nuget.org/packages/DotnetFastMCP) [](LICENSE) [](https://github.com/tekspry/.NetFastMCP)

A modern, production-ready C#/.NET framework for building secure, scalable, and observable Model Context Protocol (MCP) servers with enterprise-grade authentication.

🎯 Overview

DotnetFastMCP provides a clean, attribute-based approach to building MCP servers that implement the JSON-RPC 2.0 protocol. It includes a native .NET Client Library client for consuming MCP servers, making it a complete solution for building both sides of the Model Context Protocol. Built on ASP.NET Core, it leverages modern .NET features for high performance, reliability, and comprehensive OAuth 2.0 / OpenID Connect authentication out of the box.

⭐ Key Features

Core Framework

• ✅ Simple Attribute-Based API - Declare tools and resources with [McpTool] and [McpResource] attributes
• ✅ First-Class Prompts Support - Define prompts with [McpPrompt] for LLM interaction templates
• ✅ Automatic Component Discovery - Reflection-based scanning of assemblies
• ✅ JSON-RPC 2.0 Compliant - Full protocol compliance with proper error handling
• ✅ Flexible Parameter Binding - Supports both array and named parameters
• ✅ Built on ASP.NET Core - Leverage the powerful ASP.NET Core hosting model
• ✅ Production Ready - Comprehensive error handling and logging
• ✅ Type-Safe - Full C# type system integration

🔐 Enterprise Authentication

• ✅ 6 OAuth Providers Supported - Azure AD, Google, GitHub, Auth0, Okta, AWS Cognito
• ✅ OAuth Proxy Built-In - Automatic Dynamic Client Registration (DCR) for non-DCR providers
• ✅ JWT Token Verification - Automatic token validation with JWKS caching
• ✅ Zero Configuration - Set environment variables and go
• ✅ Sensible Defaults - Pre-configured scopes for common use cases
• ✅ Fine-Grained Authorization - Protect tools with [Authorize] attribute
• ✅ Claims-Based Access - Access user information from authenticated requests
• ✅ MFA Support - Enforce Multi-Factor Authentication for sensitive tools

🔌 Native Client Library

• ✅ McpClient - Type-safe .NET client for consuming any MCP server
• ✅ Transport Agnostic - Support for both Stdio and SSE connections
• ✅ Notification Handling - Events for real-time logs and progress
• ✅ Tool Invocation - Clean CallToolAsync API

🤖 LLM Integration

• ✅ 8 LLM Providers - Ollama, OpenAI, Azure OpenAI, Anthropic Claude, Google Gemini, Cohere, Hugging Face, Deepseek
• ✅ Latest Models (Feb 2026) - Claude Opus 4.6, Gemini 3 Pro/Flash, Command A, DeepSeek V3.2
• ✅ Unified Interface - Single ILLMProvider API for all providers
• ✅ Streaming Support - Real-time token streaming with IAsyncEnumerable
• ✅ Production-Ready - HttpClientFactory, Polly retry policies, connection pooling
• ✅ Plug-and-Play - Simple extension methods: builder.AddAnthropicProvider()

📡 Observability (v1.14.0)

• ✅ OpenTelemetry Integration - First-class metrics and distributed tracing
• ✅ 5 Auto-Tracked Metrics - Tool invocations, duration, errors, prompt requests, resource reads
• ✅ One-Line Setup - builder.WithTelemetry() — zero boilerplate
• ✅ Exporter Agnostic - Plug in Prometheus, Application Insights, Grafana, Jaeger, or any OTLP backend
• ✅ OTel Semantic Conventions - Standard tag names, exception events, span status
• ✅ Zero Overhead When Disabled - Fully opt-in, no performance cost if unused
• ✅ Stdio + HTTP - Metrics work across both transports

🏥 Health Checks & Diagnostics (NEW! v1.15.0)

• ✅ Built-In Health Endpoint - GET /mcp/health exposed automatically
• ✅ One-Line Setup - builder.WithHealthChecks() — no configuration required
• ✅ Plug-In Custom Checks - Add any check as a simple lambda (no interfaces needed)
• ✅ Parallel Execution - All checks run concurrently with per-check timeout
• ✅ Standard HTTP Status Codes - 200 Healthy / 207 Degraded / 503 Unhealthy
• ✅ Kubernetes & Docker Ready - Drop-in for liveness/readiness probes
• ✅ Auto Server Diagnostics - Tool count, uptime, framework version included
• ✅ Zero Overhead When Disabled - Fully opt-in, endpoint not registered unless configured

🚀 Quick Start

Installation

git clone https://github.com/tekspry/.NetFastMCP.git
cd DotnetFastMCP
dotnet build -c Release

Create Your First MCP Server

1. Define Your Tools

Create a static class with [McpTool]-decorated static methods:

using FastMCP.Attributes;

public static class MyTools
{
    [McpTool(Description = "Adds two numbers")]
    public static int Add(int a, int b) => a + b;

    [McpTool(Description = "Returns an echo of the input")]
    public static string Echo(string message) => message;
}

2. Create Program.cs

using FastMCP.Hosting;
using FastMCP.Server;
using System.Reflection;

var server = new FastMCPServer("MyMcpServer");
var builder = McpServerBuilder.Create(server, args);
builder.WithComponentsFrom(Assembly.GetExecutingAssembly());

var app = builder.Build();
await app.RunMcpAsync(args);

Running the Example Server

cd examples/BasicServer
dotnet run

The server will start on http://localhost:5000.

📚 Architecture

Core Components

DotnetFastMCP/
├── src/
│   ├── FastMCP/
│   │   ├── Attributes/          # Component declaration attributes
│   │   ├── Client/              # 🔌 Client library implementation
│   │   ├── Hosting/             # Server hosting and middleware
│   │   ├── Protocol/            # JSON-RPC protocol implementation
│   │   ├── Server/              # FastMCPServer core class
│   │   └── FastMCP.csproj
│   └── FastMCP.CLI/             # Command-line utilities
├── examples/
│   └── BasicServer/             # Example MCP server implementation
├── tests/
│   └── McpIntegrationTest/      # Integration tests
├── LAUNCH_TESTS.ps1             # PowerShell test suite launcher
└── RUN_AND_TEST.ps1             # PowerShell integration test script

Project Structure

| Project | Purpose | |---------|---------| | FastMCP | Core framework library | | FastMCP.CLI | Command-line interface tools | | BasicServer | Example MCP server implementation | | McpIntegrationTest | Integration tests | | ClientDemo | Example Client consuming BasicServer |

🔧 Creating an MCP Server

1. Define Components

For better organization, split your components into multiple files (e.g., Tools.cs, Resources.cs). The framework will discover them automatically.

File: Tools.cs

using FastMCP.Attributes;
using Microsoft.AspNetCore.Authorization;
using System.Security.Claims;

public static class MyTools
{
    /// 
    /// Public tool - no authentication required
    /// 
    [McpTool]
    public static int Add(int a, int b) => a + b;

public static class Resources
{
    /// 
    /// Protected tool - requires authentication
    /// 
    [McpTool]
    [Authorize]
    public static object GetUserProfile(ClaimsPrincipal user)
    {
        return new
        {
            Name = user.Identity?.Name,
            Email = user.FindFirst("email")?.Value,
            IsAuthenticated = user.Identity?.IsAuthenticated
        };
    }
}

2. Configure Server with Authentication

using FastMCP.Hosting;
using FastMCP.Server;
using System.Reflection;

var mcpServer = new FastMCPServer(name: "My Secure MCP Server");
var builder = McpServerBuilder.Create(mcpServer, args);

// Add authentication (choose your provider)
builder.AddAzureAdTokenVerifier();  // or AddGoogleTokenVerifier(), AddGitHubTokenVerifier(), etc.

// Register tools
builder.WithComponentsFrom(Assembly.GetExecutingAssembly());

var app = builder.Build();
app.Urls.Add("http://localhost:5002");
await app.RunAsync();

3. Set Environment Variables

# Windows PowerShell
$env:FASTMCP_SERVER_AUTH_AZUREAD_TENANT_ID="your-tenant-id"
$env:FASTMCP_SERVER_AUTH_AZUREAD_CLIENT_ID="your-client-id"
$env:FASTMCP_SERVER_AUTH_AZUREAD_CLIENT_SECRET="your-client-secret"

# Linux/Mac
export FASTMCP_SERVER_AUTH_AZUREAD_TENANT_ID="your-tenant-id"
export FASTMCP_SERVER_AUTH_AZUREAD_CLIENT_ID="your-client-id"
export FASTMCP_SERVER_AUTH_AZUREAD_CLIENT_SECRET="your-client-secret"

4. Run and Test

dotnet run

Your server is now running with OAuth Proxy endpoints:

• MCP endpoint: http://localhost:5002/mcp
• OAuth authorization: http://localhost:5002/oauth/authorize
• OAuth token: http://localhost:5002/oauth/token
• Discovery: http://localhost:5002/.well-known/oauth-authorization-server

Stdio Mode

You can also run the server in Stdio mode (for local LLM clients):

dotnet run -- --stdio

Create an MCP Client

Connect to any MCP server using the C# Client Library:

using FastMCP.Client;
using FastMCP.Client.Transports;

// 1. Connect (via Stdio or SSE)
var transport = new StdioClientTransport("dotnet", "run --project examples/BasicServer -- --stdio");
await using var client = new McpClient(transport);
await client.ConnectAsync();

// 2. List & Call Tools
var tools = await client.ListToolsAsync();
var result = await client.CallToolAsync("add_numbers", new { a = 10, b = 20 });

🔐 Authentication Providers

DotnetFastMCP supports 6 enterprise-grade OAuth providers out of the box:

| Provider | Method | Use Case | Default Scopes | |----------|--------|----------|----------------| | Azure AD | AddAzureAdTokenVerifier() | Enterprise apps, Microsoft 365 | openid, profile, email, offline_access | | Google | AddGoogleTokenVerifier() | Consumer apps, Google Workspace | openid, profile, email, userinfo.profile | | GitHub | AddGitHubTokenVerifier() | Developer tools, repositories | read:user, user:email | | Auth0 | AddAuth0TokenVerifier() | Multi-tenant SaaS, custom identity | openid, profile, email, offline_access | | Okta | AddOktaTokenVerifier() | Enterprise SSO, workforce identity | openid, profile, email, offline_access | | AWS Cognito | AddAwsCognitoTokenVerifier() | AWS-native apps, user pools | openid, profile, email |

Quick Setup Examples

Azure AD

builder.AddAzureAdTokenVerifier();

Environment Variables:

FASTMCP_SERVER_AUTH_AZUREAD_TENANT_ID=your-tenant-id
FASTMCP_SERVER_AUTH_AZUREAD_CLIENT_ID=your-client-id
FASTMCP_SERVER_AUTH_AZUREAD_CLIENT_SECRET=your-client-secret

Example: [examples/Auth/AzureAdOAuth](examples/Auth/AzureAdOAuth)

Google

builder.AddGoogleTokenVerifier();

Environment Variables:

FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=your-client-secret

Example: [examples/Auth/GoogleOAuth](examples/Auth/GoogleOAuth)

GitHub

builder.AddGitHubTokenVerifier();

Environment Variables:

FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID=your-github-client-id
FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET=your-github-client-secret

Example: [examples/Auth/GitHubOAuth](examples/Auth/GitHubOAuth)

PowerShell Integration Test Suite

The project includes a comprehensive PowerShell-based integration test suite that validates a running server end-to-end.

1. Publish the server (from the root of the DotnetFastMCP project):

``sh dotnet publish -c Release -o ..\publish examples\BasicServer ``

1. Run the tests:

Open a PowerShell terminal and run the launcher script from the project root: ``powershell .\LAUNCH_TESTS.ps1 ` This will open a new window, start the BasicServer`, and run a series of tests covering all tools and resources, including error handling.

Example Manual Test

Auth0

builder.AddAuth0TokenVerifier();

Environment Variables:

FASTMCP_SERVER_AUTH_AUTH0_DOMAIN=your-tenant.auth0.com
FASTMCP_SERVER_AUTH_AUTH0_AUDIENCE=https://your-api-identifier
FASTMCP_SERVER_AUTH_AUTH0_CLIENT_ID=your-client-id
FASTMCP_SERVER_AUTH_AUTH0_CLIENT_SECRET=your-client-secret

Example: [examples/Auth/Auth0OAuth](examples/Auth/Auth0OAuth)

Okta

builder.AddOktaTokenVerifier();

Environment Variables:

FASTMCP_SERVER_AUTH_OKTA_DOMAIN=dev-123456.okta.com
FASTMCP_SERVER_AUTH_OKTA_AUDIENCE=api://default
FASTMCP_SERVER_AUTH_OKTA_CLIENT_ID=your-client-id
FASTMCP_SERVER_AUTH_OKTA_CLIENT_SECRET=your-client-secret

Example: [examples/Auth/OktaOAuth](examples/Auth/OktaOAuth)

AWS Cognito

builder.AddAwsCognitoTokenVerifier();

Environment Variables:

FASTMCP_SERVER_AUTH_AWSCOGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX
FASTMCP_SERVER_AUTH_AWSCOGNITO_REGION=us-east-1
FASTMCP_SERVER_AUTH_AWSCOGNITO_CLIENT_ID=your-app-client-id
FASTMCP_SERVER_AUTH_AWSCOGNITO_CLIENT_SECRET=your-app-client-secret
FASTMCP_SERVER_AUTH_AWSCOGNITO_DOMAIN=myapp.auth.us-east-1.amazoncognito.com

Example: [examples/Auth/AwsCognitoOAuth](examples/Auth/AwsCognitoOAuth)

📚 Architecture

Project Structure

DotnetFastMCP/
├── src/
│   └── FastMCP/
│       ├── Attributes/              # Component declaration attributes
│       ├── Authentication/          # 🔐 OAuth providers & token verification
│       │   ├── Providers/          # Azure AD, Google, GitHub, Auth0, Okta, AWS
│       │   ├── Proxy/              # OAuth Proxy for DCR
│       │   └── Verification/       # JWT token validation
│       ├── Hosting/                 # Server hosting and middleware
│       ├── Protocol/                # JSON-RPC protocol implementation
│       └── Server/                  # FastMCPServer core class
├── examples/
│   ├── BasicServer/                 # Simple MCP server
│   └── Auth/                        # 🔐 Authentication examples
│       ├── AzureAdOAuth/           # Azure AD example
│       ├── GoogleOAuth/            # Google OAuth example
│       ├── GitHubOAuth/            # GitHub OAuth example
│       ├── Auth0OAuth/             # Auth0 example
│       ├── OktaOAuth/              # Okta example
│       └── AwsCognitoOAuth/        # AWS Cognito example
└── tests/
    └── McpIntegrationTest/          # Integration tests

Project Structure (Client)

The FastMCP framework now includes a complete client implementation in src/FastMCP/Client.

graph TD
    App[Your App] -->|Uses| Client[McpClient]
    Client -->|IClientTransport| Trans[Transport Layer]
    Trans -->|Stdio| Local[Local Process]
    Trans -->|SSE/HTTP| Remote[Remote Server]

Authentication Flow

sequenceDiagram
    participant Client
    participant MCP Server
    participant OAuth Provider
    
    Client->>MCP Server: Request with Bearer Token
    MCP Server->>Token Verifier: Validate Token
    Token Verifier->>OAuth Provider: Fetch JWKS (if needed)
    OAuth Provider-->>Token Verifier: Public Keys
    Token Verifier-->>MCP Server: Validated Claims
    MCP Server-->>Client: Protected Resource

🔧 Creating an MCP Server

Basic Server (No Authentication)

using FastMCP.Hosting;
using FastMCP.Server;
using System.Reflection;

var mcpServer = new FastMCPServer(name: "My MCP Server");
var builder = McpServerBuilder.Create(mcpServer, args);

builder.WithComponentsFrom(Assembly.GetExecutingAssembly());

var app = builder.Build();
await app.RunAsync();

Secure Server (With Authentication)

using FastMCP.Hosting;
using FastMCP.Server;
using System.Reflection;

var mcpServer = new FastMCPServer(name: "My Secure MCP Server");
var builder = McpServerBuilder.Create(mcpServer, args);

// Add authentication - automatically configures OAuth Proxy
builder.AddAzureAdTokenVerifier();  // or any other provider

bu

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tekspry](https://github.com/tekspry)
- **Source:** [tekspry/DotnetFastMCP](https://github.com/tekspry/DotnetFastMCP)
- **License:** MIT
- **Homepage:** https://medium.com/applied-ai-for-app-devs/dotnetfastmcp-the-fast-lane-for-building-ai-tools-in-net-efbf6218206b?sk=0ae77b467044dcd1bcd11a559c798048

Install and usage instructions live in the source repository linked above.