helix.mcp: Skill for Claude Code

Skill: Emitting MCP Progress Notifications (ModelContextProtocol C# SDK ≥ 1.3.0)

When to apply

A [McpServerTool] method routinely takes more than ~1 second (downloads, multi-step API scans, multi-file processing). The MCP client needs interim progress so its UI doesn't appear hung.

The pattern (server side, C#)

[McpServerTool(Name = "long_running_thing")]
public async Task<MyResult> Do(
    string someArg,
    int batchSize = 100,
    // Auto-injected by the SDK. Parameter is *omitted from the tool's
    // JSON schema* — clients never see it.
    IProgress<ProgressNotificationValue>? progress = null)
{
    int total = ComputeTotal();
    int step  = Math.Max(1, total / 10);   // ~10 emits over the run

    progress?.Report(new ProgressNotificationValue
    {
        Progress = 0, Total = total,
        Message = $"Starting {total} item(s)",
    });

    int done = 0;
    foreach (var item in items)
    {
        await ProcessAsync(item);
        done++;
        if (done % step == 0 || done == total)
        {
            progress?.Report(new ProgressNotificationValue
            {
                Progress = done, Total = total,
                Message  = $"Processed {done} of {total}",
            });
        }
    }
    return result;
}

Key facts about the SDK behavior

• The SDK auto-injects IProgress<ProgressNotificationValue> for any parameter of that type. You don't register or wire anything.
• If the client included _meta.progressToken in tools/call, every Report becomes a notifications/progress JSON-RPC message tagged with that token.
• If the client did NOT supply a progress token, the injected sink is a no-op. progress?.Report(...) is always safe; never branch on "did the client want progress?" — just always call it.
• ProgressNotificationValue has init-only float Progress, float? Total, string? Message. Use object-initializer syntax.
• The escape hatch McpSession.NotifyProgressAsync(ProgressToken, …) exists for code that has a RequestContext but isn't inside a tool method's parameter frame. Don't reach for it from a tool method.