C# MCP Server Testing

Test MCP servers at two levels: unit tests for individual tool methods, and integration tests that exercise the full MCP protocol in-memory.

When to Use

• Adding automated tests to an MCP server
• Testing individual tool methods with mocked dependencies
• Writing integration tests that validate tool listing and invocation via MCP protocol
• Setting up CI test pipelines for MCP servers

Stop Signals

• No server yet? → Use mcp-csharp-create first
• Server not running? → Use mcp-csharp-debug
• Just need manual/interactive testing? → Use mcp-csharp-debug for MCP Inspector

Inputs

| Input | Required | Description | |-------|----------|-------------| | MCP server project path | Yes | Path to the server .csproj being tested | | Test framework | Recommended | Default: xUnit. Also supports NUnit or MSTest | | Transport type | Recommended | Determines integration test approach (stdio vs HTTP) |

Workflow

Step 1: Create the test project

bash
dotnet new xunit -n <ServerName>.Tests
cd <ServerName>.Tests
dotnet add reference ../<ServerName>/<ServerName>.csproj
dotnet add package ModelContextProtocol
dotnet add package Moq
dotnet add package FluentAssertions

Step 2: Write unit tests for tool methods

Test tool methods directly — fastest and most isolated:

csharp
public class MyToolTests
{
    [Fact]
    public void Echo_ReturnsFormattedMessage()
    {
        var result = MyTools.Echo("Hello");
        result.Should().Be("Echo: Hello");
    }

    [Theory]
    [InlineData("")]
    [InlineData("   ")]
    public void Echo_HandlesEdgeCases(string input)
    {
        var result = MyTools.Echo(input);
        result.Should().StartWith("Echo:");
    }
}

For tools with DI dependencies, mock the dependency:

csharp
public class ApiToolTests
{
    [Fact]
    public async Task FetchData_ReturnsApiResponse()
    {
        var handler = new MockHttpMessageHandler("""{"id": 1}""");
        var httpClient = new HttpClient(handler);

        var result = await ApiTools.FetchData(httpClient, "resource-1");
        result.Should().Contain("id");
    }
}

Step 3: Write integration tests with MCP client

Test the full MCP protocol using a client-server connection:

csharp
using ModelContextProtocol.Client;

public class ServerIntegrationTests : IAsyncLifetime
{
    private McpClient _client = null!;

    public async Task InitializeAsync()
    {
        var transport = new StdioClientTransport(new StdioClientTransportOptions
        {
            Name = "TestClient",
            Command = "dotnet",
            Arguments = ["run", "--project", "../<ServerName>/<ServerName>.csproj"]
        });
        _client = await McpClient.CreateAsync(transport);
    }

    public async Task DisposeAsync() => await _client.DisposeAsync();

    [Fact]
    public async Task Server_ListsExpectedTools()
    {
        var tools = await _client.ListToolsAsync();
        tools.Should().Contain(t => t.Name == "echo");
    }

    [Fact]
    public async Task Tool_ReturnsExpectedResult()
    {
        var result = await _client.CallToolAsync("echo",
            new Dictionary<string, object?> { ["message"] = "Test" });
        var text = result.Content.OfType<TextContentBlock>().First().Text;
        text.Should().Contain("Test");
    }
}

For the SDK's ClientServerTestBase (in-memory testing) and HTTP testing with WebApplicationFactory, see references/test-patterns.md.

Step 4: Run tests

bash
# Run all tests
dotnet test

# Run a specific test class
dotnet test --filter "FullyQualifiedName~MyToolTests"

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

Step 5: Write evaluations

Evaluations measure how well an LLM uses your tools. Good evaluation questions should be:

• Read-only and non-destructive — never modify data as a side effect
• Deterministic — have a single verifiable correct answer
• Multi-step — require the LLM to call multiple tools or reason across results

For the evaluation format, example questions, and detailed guidance, see references/evaluations.md.

Validation

• ] Unit tests cover all tool methods, including edge cases
• ] Integration tests verify tool listing via ListToolsAsync()
• ] Integration tests verify tool invocation via CallToolAsync()
• ] All tests pass: dotnet test
• ] Tests run in CI without manual setup

Common Pitfalls

| Pitfall | Solution | |---------|----------| | Integration test hangs on CreateAsync | Server fails to start. Verify dotnet build succeeds first. For stdio, ensure no stdout logging | | StdioClientTransport not finding project | Use the correct relative path to .csproj from the test project directory | | Tests pass locally but fail in CI | Run dotnet build before test execution. Use --no-build only after an explicit build step | | Mocking HttpClient is awkward | Mock HttpMessageHandler, not HttpClient directly. See references/test-patterns.md | | Full test suite runs are slow | Use --filter for development. Run the full suite only for CI verification |

Related Skills

• mcp-csharp-create — Create a new MCP server project
• mcp-csharp-debug — Running and interactive debugging
• mcp-csharp-publish — NuGet, Docker, Azure deployment

Reference Files

• references/test-patterns.md — Complete test code examples: ClientServerTestBase in-memory pattern, WebApplicationFactory for HTTP, MockHttpMessageHandler helper, test categorization, coverage reporting. Load when: writing integration tests or need detailed mock patterns.
• references/evaluations.md — Evaluation format, question design principles, and example eval questions. Load when: user asks about evaluations, eval questions, or measuring tool quality.

More Info

• xUnit documentation — Getting started with xUnit for .NET