Skip to content
Awesome GitHub Copilot

Csharp Mcp Server

Csharp Mcp Server

Instructions for building Model Context Protocol (MCP) servers using the C# SDK

Documentation

C# MCP Server Development

Instructions

  • Use the ModelContextProtocol NuGet package (prerelease) for most projects: dotnet add package ModelContextProtocol --prerelease
  • Use ModelContextProtocol.AspNetCore for HTTP-based MCP servers
  • Use ModelContextProtocol.Core for minimal dependencies (client-only or low-level server APIs)
  • Always configure logging to stderr using LogToStandardErrorThreshold = LogLevel.Trace to avoid interfering with stdio transport
  • Use the [McpServerToolType] attribute on classes containing MCP tools
  • Use the [McpServerTool] attribute on methods to expose them as tools
  • Use the [Description] attribute from System.ComponentModel to document tools and parameters
  • Support dependency injection in tool methods - inject McpServer, HttpClient, or other services as parameters
  • Use McpServer.AsSamplingChatClient() to make sampling requests back to the client from within tools
  • Expose prompts using [McpServerPromptType] on classes and [McpServerPrompt] on methods
  • For stdio transport, use WithStdioServerTransport() when building the server
  • Use WithToolsFromAssembly() to auto-discover and register all tools from the current assembly
  • Tool methods can be synchronous or async (return Task or Task<T>)
  • Always include comprehensive descriptions for tools and parameters to help LLMs understand their purpose
  • Use CancellationToken parameters in async tools for proper cancellation support
  • Return simple types (string, int, etc.) or complex objects that can be serialized to JSON
  • For fine-grained control, use McpServerOptions with custom handlers like ListToolsHandler and CallToolHandler
  • Use McpProtocolException for protocol-level errors with appropriate McpErrorCode values
  • Test MCP servers using the McpClient from the same SDK or any compliant MCP client
  • Structure projects with Microsoft.Extensions.Hosting for proper DI and lifecycle management

Best Practices

  • Keep tool methods focused and single-purpose
  • Use meaningful tool names that clearly indicate their function
  • Provide detailed descriptions that explain what the tool does, what parameters it expects, and what it returns
  • Validate input parameters and throw McpProtocolException with McpErrorCode.InvalidParams for invalid inputs
  • Use structured logging to help with debugging without polluting stdout
  • Organize related tools into logical classes with [McpServerToolType]
  • Consider security implications when exposing tools that access external resources
  • Use the built-in DI container to manage service lifetimes and dependencies
  • Implement proper error handling and return meaningful error messages
  • Test tools individually before integrating with LLMs

Common Patterns

Basic Server Setup

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddConsole(options => 
    options.LogToStandardErrorThreshold = LogLevel.Trace);
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();
await builder.Build().RunAsync();

Simple Tool

[McpServerToolType]
public static class MyTools
{
    [McpServerTool, Description("Description of what the tool does")]
    public static string ToolName(
        [Description("Parameter description")] string param) => 
        $"Result: {param}";
}

Tool with Dependency Injection

[McpServerTool, Description("Fetches data from a URL")]
public static async Task<string> FetchData(
    HttpClient httpClient,
    [Description("The URL to fetch")] string url,
    CancellationToken cancellationToken) =>
    await httpClient.GetStringAsync(url, cancellationToken);

Tool with Sampling

[McpServerTool, Description("Analyzes content using the client's LLM")]
public static async Task<string> Analyze(
    McpServer server,
    [Description("Content to analyze")] string content,
    CancellationToken cancellationToken)
{
    var messages = new ChatMessage[]
    {
        new(ChatRole.User, $"Analyze this: {content}")
    };
    return await server.AsSamplingChatClient()
        .GetResponseAsync(messages, cancellationToken: cancellationToken);
}