awesome-claude-copilot csharp-mcp-server.instructions.md

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