DEV Community: Sukhpinder Singh

Claude API Workspace Verification: Catch Misrouted Requests Before Attribution

Sukhpinder Singh — Fri, 28 Aug 2026 15:35:07 +0000

Claude API workspace verification is a small check that closes an awkward observability gap. A multi-workspace credential can send a request toward one workspace, while a stale deployment setting, copied ID, or routing mistake points somewhere else. If I record only the configured workspace, every later cost and resource lookup begins with an assumption.

Anthropic now returns anthropic-workspace-id on workspace-resolved Claude API responses. I first compare routing configuration with an independently owned authorization mapping, then compare that authoritative response value with the authorized workspace before the application parses, persists, or attributes the result.

Why Claude API workspace verification belongs on the response

The Anthropic workspace documentation separates two ideas that are easy to blur together. A request can carry anthropic-workspace-id when a multi-workspace key selects its target. A successful response carries the workspace that the credential actually resolved to.

That second value is useful evidence. Configuration tells me what the application meant to do. The response tells me where the provider handled the request.

This matters beyond cost dashboards. Files, message batches, Skills, prompt caches, and other resources can be workspace-scoped. If I save a resource ID under the wrong internal tenant or environment, the failure often appears later as a missing resource, an unexpected quota, or usage that seems to vanish.

The fix is not to log more configuration. I use two independently governed inputs: a routing target and an authorized tenant-to-workspace mapping. I assert both invariants at the HTTP boundary:

routing target == authorized workspace == resolved response workspace

If both expected values are aliases for one unchecked setting, the first comparison adds no protection. In my sample, the authorization mapping is a distinct parameter so that a stale deployment target fails before any request leaves the process.

I also keep the provider request-id beside the verified workspace. That pair is much more useful during support and attribution work than the configured value alone.

Compare intent with the resolved workspace

The check should run after the HTTP status succeeds but before the body reaches application code. Anthropic documents the response headers in its API overview, and official SDKs expose raw-response accessors for reading them.

Here is the core of the .NET sample:

response.EnsureSuccessStatusCode();

if (!response.Headers.TryGetValues(
        "anthropic-workspace-id", out var values))
{
    throw new InvalidDataException(
        "Successful response omitted anthropic-workspace-id.");
}

var actual = values.Single();
if (!string.Equals(actual, expected, StringComparison.Ordinal))
{
    throw new InvalidDataException(
        $"Resolved {actual}; expected {expected}.");
}

return await response.Content.ReadAsStringAsync();

I validate the routing, authorized, and returned values as wrkspc_ followed by an alphanumeric identifier. I reject a routing-versus-authorization mismatch before sending. After success, I require exactly one response value and compare with ordinal equality. A provider mismatch fails before a caller can parse or store the payload.

For a multi-workspace key, the routing target is sent on the request while the authorized value comes from a separately reviewed tenant registry or environment allowlist. This sample is intentionally limited to that path. A separate wrapper for a key already bound to one workspace could omit the outbound selector and still verify the response against an independently authorized workspace.

Do not replace the original HTTP failure with a workspace error. Anthropic says the header can be absent when authentication does not complete, such as a 401 response. Calling EnsureSuccessStatusCode first preserves the useful authentication failure; header verification applies to the successful workspace-scoped response.

Make the workspace check deterministic

The complete sample uses a fake HttpMessageHandler, so it never calls Anthropic and needs no credential. Its fixtures run seven checks across these paths:

matching routing, authorization, and response values pass;
stale routing is rejected before the transport runs;
a different response workspace fails before body use;
a missing or malformed workspace on success fails closed;
invalid configuration makes no HTTP request; and
a 401 remains an authentication error even without the header.

This is the kind of contract test I want in CI. It is fast, has no model output to compare, and makes a deployment invariant executable. I can add one fixture for each configured environment without creating API keys or spending tokens.

In a live service, the authorization value should come from a reviewed mapping that is independent of the component choosing the routing header. The API key still belongs in a secret store. The workspace ID is an identifier rather than an authentication secret, but I avoid scattering it through business logic because that makes routing changes harder to audit.

Limits and when not to enforce it

This guard is not authorization. A matching header does not prove that an end user may access a resource, and it does not replace provider authentication or application tenant checks. It only proves that this successful response resolved to the workspace the application expected.

Do not require the header on Admin API calls or failures that occur before authentication. Applications that intentionally route across several workspaces also need an explicit, independently governed per-request mapping rather than one process-wide expected value. Copying the routing setting into the authorization check would only verify provider resolution, not business intent.

The Default Workspace deserves one final caution. It has a real wrkspc_ ID in response headers, even though List Workspaces omits it and some usage or Admin API fields represent it as null. Store the returned ID for request tracing; do not translate it to null inside this verification step.

Would you fail a mismatched workspace immediately, or quarantine the response for investigation?

Happy coding!

Claude Structured Outputs Refusal Handling: Stop Parsing HTTP 200 Refusals

Sukhpinder Singh — Fri, 28 Aug 2026 02:04:28 +0000

Claude structured outputs refusal handling belongs before domain deserialization. A successful HTTP exchange only says the API accepted and processed the request; it does not guarantee that the text block contains the JSON object my application expects. Claude can return an HTTP 200 response with stop_reason: "refusal", and a response stopped by max_tokens can contain incomplete JSON. If I unwrap content[0].text and immediately call JsonSerializer.Deserialize, I turn a documented response state into a misleading parsing failure.

The safer boundary is small: inspect the response envelope, classify the stop reason, and deserialize only a completed structured result.

The schema is only one part of the contract

For the current stable API, I put the JSON Schema under output_config.format. This replaces the earlier beta output_format request shape, and the beta header is no longer required. The official structured outputs guide documents the current request format and its exceptional cases.

The relevant part of a request looks like this:

{
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": ["approve", "escalate"]
          },
          "reason": { "type": "string" }
        },
        "required": ["action", "reason"],
        "additionalProperties": false
      }
    }
  }
}

Structured outputs normally give me schema-compliant JSON, but I still treat the envelope as authoritative. A refusal is a valid API response and may not follow my output schema. A max_tokens stop can cut the generated document short. The stop-reason guidance explains why each reason needs deliberate handling instead of a blanket success path.

There is one more subtlety: enum and const text can differ in letter casing. I do not weaken validation into “accept any string.” I normalize casing only while matching against the finite enum declared by my application.

Make Claude structured outputs refusal handling a decoder boundary

I model decoding as a result, not an exception-driven happy path. The decoder first parses the outer message envelope, reads stop_reason, and rejects refusal or truncation. Only then does it pass the text block to JsonSerializer.Deserialize.

using System.Text.Json;
using System.Text.Json.Serialization;

public enum DecodeStatus { Success, Refusal, Truncated, InvalidPayload }
public enum ReviewAction { Approve, Escalate }

public sealed record ReviewWire(
    [property: JsonPropertyName("action")] string Action,
    [property: JsonPropertyName("reason")] string Reason);
public sealed record ReviewResult(ReviewAction Action, string Reason);
public sealed record DecodeResult(DecodeStatus Status, ReviewResult? Value);

public static DecodeResult Decode(string messageJson)
{
    using var message = JsonDocument.Parse(messageJson);
    var root = message.RootElement;
    var stopReason = root.GetProperty("stop_reason").GetString();

    // Gate on the response envelope before touching structured text.
    if (stopReason == "refusal")
        return new(DecodeStatus.Refusal, null);

    if (stopReason == "max_tokens")
        return new(DecodeStatus.Truncated, null);

    if (stopReason != "end_turn" || !TryGetTextBlock(root, out var text))
        return new(DecodeStatus.InvalidPayload, null);

    try
    {
        var wire = JsonSerializer.Deserialize<ReviewWire>(
            text,
            JsonSerializerOptions.Strict);

        if (wire is null || !TryMapAction(wire.Action, out var action))
            return new(DecodeStatus.InvalidPayload, null);

        return new(DecodeStatus.Success, new(action, wire.Reason));
    }
    catch (JsonException)
    {
        return new(DecodeStatus.InvalidPayload, null);
    }
}

static bool TryMapAction(string value, out ReviewAction action)
{
    if (value.Equals("approve", StringComparison.OrdinalIgnoreCase))
    {
        action = ReviewAction.Approve;
        return true;
    }

    if (value.Equals("escalate", StringComparison.OrdinalIgnoreCase))
    {
        action = ReviewAction.Escalate;
        return true;
    }

    action = default;
    return false;
}

This order is the key behavior. A refusal containing prose never reaches the inner deserializer. Truncated JSON is classified as truncation, not reported as a random syntax defect. An enum value such as APPROVE maps to the declared Approve member, while an undeclared value still fails.

In the complete sample, TryGetTextBlock scans the content array instead of assuming the first block is text. The outer parser also turns a missing stop_reason, missing text block, or malformed message body into an envelope failure. That separation keeps transport shape, generation outcome, and business data as three observable contracts rather than one catch-all JSON exception.

Prove the edge cases offline

I keep API transport out of decoder tests. Small response fixtures make the contract deterministic and avoid paid model calls. At minimum, I test four messages: a valid end_turn response, an HTTP 200 refusal with non-schema text, a max_tokens response with truncated JSON, and a completed response whose enum casing differs.

Each test asserts the classification as well as the absence or presence of a domain value. That prevents a later refactor from moving deserialization above the stop-reason gate. It also avoids brittle assertions about generated wording.

I deliberately put invalid inner text in the refusal and truncation fixtures. If a future change parses either payload too early, the verifier fails for the wrong classification immediately. A separate end_turn fixture contains malformed JSON and must produce InvalidPayload; this proves the inner parser still reports a real contract defect when the envelope says generation completed.

The runnable sample includes those fixtures, source, and test commands. The associated pull request shows the complete change and validation record.

Limitations and when not to use this pattern

This decoder is intentionally strict: it accepts end_turn for a request that expects one text result. If I intentionally use stop sequences, tool calls, or streaming, I need a state machine and an allowlist designed for those response paths. I would not silently treat every unfamiliar stop reason as success.

I also would not automatically retry a refusal. A refusal is not a transport outage, and retrying the same request can waste capacity without changing the outcome. For max_tokens, a caller can choose to reduce the requested structure or adjust its token budget, but that policy belongs above the decoder.

Finally, case-insensitive enum matching is appropriate only when casing is not meaningful in the domain. The declared values remain the boundary; normalization should never turn arbitrary model text into an accepted business decision.

Where does your integration currently check stop_reason: before deserialization, or only after parsing fails?

Happy coding!

.NET 10 ActivitySamplingResult PropagationData: Why Recorded Turns False

Sukhpinder Singh — Thu, 27 Aug 2026 16:21:09 +0000

.NET 10 changed a small tracing rule that can quietly invalidate a custom sampler. With .NET 10 ActivitySamplingResult PropagationData, a child activity no longer becomes Recorded just because its parent carries the recorded flag. The trace identity still flows, but the local sampling decision now wins.

I treat that decision as a contract worth testing. A collector is not required to reproduce it, and an exporter can actually hide the important part behind more configuration. A fixed ActivityContext, one ActivityListener, and a few assertions are enough.

Why .NET 10 ActivitySamplingResult PropagationData changed

ActivitySource.StartActivity only creates an activity when a registered listener asks for one. The listener's sampling result also says how much data the activity should collect.

The relevant choices are:

None: do not create the activity.
PropagationData: create it with propagation state, but do not request enrichment or recording.
AllData: request tags, links, and events without setting Recorded.
AllDataAndRecorded: request enrichment and set the recorded flag.

Before .NET 10, PropagationData had an exception to that table. If the parent was recorded, the child also became recorded. Microsoft changed this because the inherited flag did not match the sampling result or the OpenTelemetry contract. The .NET 10 compatibility note now states that a PropagationData child has both Recorded == false and IsAllDataRequested == false, even under a recorded parent.

That distinction matters in custom listeners. Recorded controls the W3C recorded bit propagated downstream. IsAllDataRequested tells instrumentation whether detailed data should be attached. They answer different questions, so forcing one does not automatically enable the other. The ActivitySamplingResult API documentation is a useful compact reference for those four choices.

Reproduce the Recorded flag in one process

I start with a listener whose decision is explicit and a remote parent whose IDs are fixed test data:

var decision = ActivitySamplingResult.PropagationData;
using var source = new ActivitySource("ActivityPropagationSampling", "1.0.0");
using var listener = new ActivityListener
{
    ShouldListenTo = candidate => candidate.Name == source.Name,
    Sample = (ref ActivityCreationOptions<ActivityContext> _) => decision
};

ActivitySource.AddActivityListener(listener);

var parent = new ActivityContext(
    ActivityTraceId.CreateFromString("11111111111111111111111111111111"),
    ActivitySpanId.CreateFromString("2222222222222222"),
    ActivityTraceFlags.Recorded,
    traceState: null,
    isRemote: true);

using var child = source.StartActivity(
    "receive-message",
    ActivityKind.Consumer,
    parent);

The important assertions are about the contract, not generated identifiers or wall-clock timing:

Debug.Assert(child is not null);
Debug.Assert(child.TraceId == parent.TraceId);
Debug.Assert(child.ParentSpanId == parent.SpanId);
Debug.Assert(child.Recorded is false);
Debug.Assert(child.IsAllDataRequested is false);

The child exists and continues the trace, which is exactly what PropagationData requests. It simply does not claim that this process chose to record or enrich it.

The complete sample on main turns these checks into a deterministic console verifier. It runs without credentials, network calls, model calls, an OpenTelemetry package, or a collector. The merged pull request also records the validation commands and results.

Run it with:

dotnet restore
dotnet format --verify-no-changes --no-restore
dotnet build -c Release --no-restore
dotnet run -c Release --no-build

The verifier ends with PASS: 10/10 checks. Five repeated runs produced byte-identical output in the sample validation, but I am not presenting that as a performance benchmark. It only proves that the fixture itself is stable.

Choose the sampling result deliberately

If I only need trace identity and baggage to cross a boundary, PropagationData is still the right answer. Changing it to AllDataAndRecorded merely to preserve pre-.NET 10 behavior can increase the amount of telemetry collected.

If the listener truly intends to record and enrich the activity, I return AllDataAndRecorded and test both flags. If I need the old recorded bit temporarily, Microsoft's documented compatibility measure is explicit:

child.ActivityTraceFlags |= ActivityTraceFlags.Recorded;

That line makes child.Recorded true and propagates the bit downstream. It does not make IsAllDataRequested true. Code that sets tags or events based on that property will still skip enrichment, so this is a narrow bridge rather than a replacement sampling policy.

I also keep the framework baseline visible. The sample was verified on the stable .NET 10.0.11 runtime included with SDK 10.0.303; Microsoft's 10.0.11 release notes list that supported SDK/runtime pairing.

Limits and when not to change anything

This behavior targets code that directly implements ActivityListener.Sample and returns PropagationData. Microsoft notes that the default OpenTelemetry .NET parent-based sampler is not affected. If that is your setup, do not add a flag override for a problem you do not have.

The sample also stops at the in-process contract. It does not prove exporter batching, collector sampling, backend retention, or billing behavior. Those belong in separate integration checks because they depend on the telemetry stack you deploy.

For custom samplers, though, this small test catches the exact upgrade boundary without external infrastructure. How are you regression-testing sampling decisions in your tracing code?

Happy coding!

.NET 10 BufferedStream WriteByte: Flush Full Buffers Explicitly

Sukhpinder Singh — Tue, 25 Aug 2026 23:26:11 +0000

BufferedStream.WriteByte had a surprising side effect through .NET 9: the call at its internal capacity boundary also called Flush() on the wrapped stream. The .NET 10 BufferedStream WriteByte behavior removes that implicit flush. Bytes can still move to the underlying stream when the buffer needs room, but that capacity boundary no longer becomes an accidental flush boundary.

That distinction matters when a custom stream, protocol adapter, compressor, or test double gives Flush() observable meaning. The application may still deliver the right bytes eventually while missing the side effect it previously got at a particular point.

Why .NET 10 BufferedStream WriteByte changed

Microsoft documents this as a .NET 10 behavioral change. WriteByte used to differ from the other BufferedStream.Write methods by flushing the underlying stream when a byte write reached its capacity boundary. .NET 10 removes that inconsistency.

This is stable behavior in .NET 10 LTS, not a preview feature. I verified the sample with SDK 10.0.303 and the 10.0.11 runtime, alongside runtime 9.0.18 for the old contract.

The word “flush” needs care here. BufferedStream can write buffered bytes to its destination to make room without calling the destination's Flush() method. The breaking change is about that method call, not a promise that every byte stays inside BufferedStream until disposal.

Reproduce the old and new flush boundary

I prefer an executable contract over guessing from a MemoryStream.Length check. The complete multi-target verifier wraps a memory stream and counts both writes and flushes:

internal sealed class TrackingStream : MemoryStream
{
    public int FlushCalls { get; private set; }
    public int WriteCalls { get; private set; }

    public override void Flush()
    {
        FlushCalls++;
        base.Flush();
    }

    public override void Write(ReadOnlySpan<byte> buffer)
    {
        WriteCalls++;
        base.Write(buffer);
    }

    public override void Write(byte[] buffer, int offset, int count)
    {
        WriteCalls++;
        base.Write(buffer, offset, count);
    }
}

The test uses a four-byte buffer and writes exactly four bytes:

byte[] payload = [1, 2, 3, 4];
using TrackingStream sink = new();
using BufferedStream buffered = new(sink, bufferSize: 4);

foreach (byte value in payload)
{
    buffered.WriteByte(value);
}

Console.WriteLine(
    $"flushes={sink.FlushCalls}, bytes={Convert.ToHexString(sink.ToArray())}");

The result before an explicit flush is precise:

net9.0:  flushes=1, writes=1, bytes=010203
net10.0: flushes=0, writes=1, bytes=010203

Both runtimes write the first three bytes to make room and retain the fourth byte in the buffer. Only .NET 9 also calls Flush() on the destination. That is the regression test worth preserving.

After buffered.Flush(), both targets contain 01020304 in order. The explicit call adds exactly one destination flush and one write for the remaining byte. The sample asserts seven contracts on each framework and repeats with byte-identical output.

Make the boundary explicit

The fix is not to recreate the old buffer-size accident. Put the flush where the application owns a real boundary:

foreach (byte value in encodedRecord)
{
    buffered.WriteByte(value);
}

buffered.Flush(); // The logical record is complete.

For an asynchronous pipeline, use FlushAsync(cancellationToken) at the equivalent record or batch boundary. The BufferedStream.Flush contract sends buffered data to the underlying stream and clears the buffer. It is clearer than depending on an internal capacity that could change with construction or implementation details.

I would also add a contract test around the stream that actually matters. A counter-based fake is good for proving call order. A protocol fixture can go further and verify that one complete record becomes observable only after the chosen flush. Neither test needs a network service.

Avoid flushing after every byte. That discards the batching benefit that justified BufferedStream in the first place. A record, frame, or bounded batch is usually a better unit.

Limits and when not to use this

If the code only needs all bytes when the stream is disposed, and the wrapped stream gives Flush() no special side effect, no change may be required. Disposal still provides the final boundary.

An explicit managed flush is also not automatically a durability guarantee. A memory stream, network stream, compressor, and file stream can assign different meaning to Flush(). If the requirement is physical-media durability, test and invoke the storage-specific durability operation after draining BufferedStream.

The main migration rule is small: do not use internal buffer capacity as application control flow. Name the boundary your protocol or storage contract actually needs, flush there, and verify it offline.

Where does your code need that boundary: after a record, after a batch, or only during shutdown?

Happy debugging!

.NET 10 NU1510 Package Pruning: Fix CI Without Breaking Legacy Targets

Sukhpinder Singh — Mon, 24 Aug 2026 22:23:40 +0000

.NET 10 NU1510 package pruning can turn an SDK upgrade into a failed restore when a repository promotes warnings to errors. The tempting fix is to delete the named PackageReference everywhere.

That is safe for a net10.0-only application when the framework supplies the assembly, but it can break a library that still targets netstandard2.0. I treat NU1510 as a target-specific dependency decision: prove where the reference is redundant, retain it where it is required, and verify the package produced for consumers.

Why NU1510 becomes a CI failure

Beginning with .NET 10, package pruning is enabled by default for projects targeting .NET 10 or later. NuGet raises NU1510 when a direct reference to a package registered for pruning can be completely removed because the targeted SDK supplies the same or a higher assembly version.

The NU1510 diagnostic reference is precise about that boundary. This is not a general-purpose unused-package detector, and it does not apply automatically to arbitrary third-party packages.

The sample applies a CI-style policy globally:

<Project>
  <PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>
</Project>

Its intentionally broken net10.0 project then adds this direct reference:

<ItemGroup>
  <PackageReference Include="System.Text.Json" Version="10.0.11" />
</ItemGroup>

With the stable .NET SDK 10.0.303 used for the sample, restore exits with code 1 because NU1510 is promoted from a warning to an error. Without a warnings-as-errors policy, the same condition is normally a warning rather than a failed restore.

Microsoft's .NET 10 breaking-change guidance recommends removing the reference when every target can prune it, or conditioning it when an older target still needs it.

Fix .NET 10 NU1510 package pruning per target

For the net10.0-only application, the fix is simply to remove the package reference:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
</Project>

The application still imports System.Text.Json and serializes the same payload. Its verified output is:

{"Message":"framework-provided","Count":10}

A multi-target library needs a different answer. The sample supports netstandard2.0 and net10.0, so deleting the reference globally would remove a dependency required by the older target. I make that requirement explicit in MSBuild:

<PropertyGroup>
  <TargetFrameworks>netstandard2.0;net10.0</TargetFrameworks>
</PropertyGroup>

<ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
  <PackageReference Include="System.Text.Json" Version="10.0.11" />
</ItemGroup>

An unconditioned reference that remains necessary for one runtime target does not produce NU1510, because it cannot be removed from every target. Current pack behavior also omits a prunable dependency from the net10.0 group while retaining it for the older target. I use the explicit condition to make the intent reviewable, not because every unconditioned multi-target reference is wrong.

NuGet restore creates a separate dependency graph for each target framework, and dotnet pack produces framework-specific dependency metadata. The PackageReference documentation documents target conditions. For a larger framework matrix, a compatibility-based condition may be easier to maintain, but it still needs verification against every supported target.

Verify the dependency graph, not only the warning

I do not consider a disappearing warning sufficient evidence. A library fix must also preserve the dependency contract seen by package consumers.

The sample runs its checks with:

dotnet restore .\Verifier\Verifier.csproj
dotnet build .\Verifier\Verifier.csproj --configuration Release --no-restore
dotnet run --project .\Verifier\Verifier.csproj --configuration Release --no-build --no-restore
dotnet format whitespace .\Nu1510PackagePruning.slnx --verify-no-changes --no-restore

The verifier owns the expected failure, so the broken project is deliberately excluded from the solution. It checks nine behaviors: the broken restore fails with NU1510; the diagnostic names System.Text.Json; the fixed application runs; the fixed assets contain no package copy; and the multi-target assets plus packed .nuspec keep the dependency only for netstandard2.0.

The completed verifier reports PASS 9/9. Five repeated runs also produced byte-identical output. You can inspect the complete runnable sample and the merged pull request.

This distinction matters: the sample executes the modern application, while the older library target is validated through restore, build, assets metadata, and the packed .nuspec. It does not claim to execute a netstandard2.0 application.

Limitations and when not to remove a reference

This approach applies only when the SDK or a referenced framework has registered a package for pruning. A custom package is not made redundant merely because its namespace resembles framework functionality.

The sample covers the SDK-provided System.Text.Json case. It does not model the separate FrameworkReference and transitive ProjectReference scenario described in the diagnostic documentation. It also makes no benchmark claim about restore size or speed.

Before removing a reference in a real library, I would restore, build, test, and pack every supported target. I would also inspect the resulting dependency groups, especially when central package management or more complex MSBuild conditions are involved. Suppressing NU1510 may unblock a migration temporarily, but it does not establish whether the published dependency contract is correct.

Which multi-targeted package reference will you audit before your next .NET 10 upgrade?

Happy coding!

MCP Pagination Empty `nextCursor`: Don't Stop After Page One

Sukhpinder Singh — Mon, 24 Aug 2026 19:51:37 +0000

MCP pagination empty nextCursor handling looks like a tiny null check, but the wrong predicate can hide most of a server's catalog. In the final 2026-07-28 specification, cursors are opaque strings. An empty string is valid; only a missing nextCursor ends traversal. In a nullable C# response model, that absence is represented by null. I built a small .NET 10 verifier because this failure is unusually quiet: the request succeeds, the first page looks reasonable, and no error says that later pages never arrived.

Why MCP pagination empty nextCursor breaks quietly

MCP uses cursor pagination for tools/list, prompts/list, resources/list, and resources/templates/list. The server chooses each page size, so a client cannot infer completion from the number of returned items.

The official pagination specification gives the reliable rule: continue whenever the response supplies a non-null nextCursor. The client must pass that token back without parsing or changing it. The empty string is still a supplied token.

Stripped to the fields relevant to this bug, an intermediate response can contain:

{
  "result": {
    "tools": [{ "name": "catalog.search" }],
    "nextCursor": ""
  }
}

That JSON is a pagination excerpt, not a complete MCP wire message. A conforming response still needs its JSON-RPC envelope and the other required result metadata, while every 2026-07-28 request needs the required _meta. None of those fields changes the cursor termination rule.

A common C# loop accidentally treats that response as the last page:

string? cursor = null;

do
{
    var page = await pager.ListToolsAsync(cursor, cancellationToken);
    tools.AddRange(page.Tools);
    cursor = page.NextCursor;
}
while (!string.IsNullOrEmpty(cursor));

IsNullOrEmpty combines two states that have different protocol meanings. A missing field, represented by null in this DTO, means finished. Empty means make another request with cursor: "".

The symptom can outlive the original request. If the client caches the partial catalog, later tool selection operates on the same incomplete view until that cache expires. Counting returned tools is not a safe fallback because the server controls page size and a one-item page may be perfectly legitimate. I prefer tests that assert the sequence of requested cursor values, not just the final item count.

Reproduce the page-one bug offline

My fake tools/list server has three deterministic pages. The first request omits the cursor. Page one returns ""; page two returns opaque:/+==; page three omits nextCursor, which the C# page model represents as null.

var page = cursor switch
{
    null => new ToolPage(["catalog.search"], string.Empty),
    "" => new ToolPage(["catalog.lookup"], "opaque:/+=="),
    "opaque:/+==" => new ToolPage(["catalog.health"], null),
    _ => throw new McpProtocolException(-32602, "Invalid cursor")
};

The broken loop returns only catalog.search. That is more dangerous than a loud exception because a user may simply believe the server exposes one tool.

The opaque second token contains punctuation on purpose. A client that decodes, trims, normalizes, or reconstructs it is also violating the contract. An unknown token triggers -32602, the specification's recommended Invalid params response for a bad cursor.

The complete runnable sample on main performs eight checks without an MCP server, credential, model call, clock, or random input. The merged pull request records the exact validation commands and results.

Fix the loop by testing only for null

The corrected loop makes the protocol distinction explicit:

for (var pageNumber = 1; pageNumber <= maxPages; pageNumber++)
{
    var page = await pager.ListToolsAsync(cursor, cancellationToken);
    tools.AddRange(page.Tools);

    if (page.NextCursor is null)
    {
        return tools;
    }

    cursor = page.NextCursor;
}

throw new InvalidOperationException("Pagination exceeded its page limit.");

This version forwards both "" and opaque:/+== without changing their string values. It also includes cancellation and a page cap so a faulty server cannot keep the client in an unbounded loop. The cap is an application guard, not a conclusion derived from a cursor's contents.

In production, I would also check the mapping layer, not only the loop. A nullable string can represent the optional field correctly because absence maps to null, while "" remains non-null. Explicit JSON null is outside the 2026-07-28 cursor schema, so a strict mapper should reject it rather than treat it as a normal terminator. A custom converter, DTO mapper, or helper such as NullIfEmpty can erase the valid empty-string distinction before pagination code sees it. A transport-level regression matrix should therefore cover an absent field, malformed explicit null, an empty string, and a punctuation-heavy token.

The 2026-07-28 release announcement confirms that this is the released specification and that the Tier 1 SDKs were updated for it. Even when an SDK offers a pagination helper, I still want a boundary test with an empty token. It catches wrappers that apply a language's truthiness rules after the SDK returns a page.

Limits and when not to write your own pager

This verifier isolates cursor control. It does not implement JSON-RPC framing, transports, authentication, required request _meta, cache metadata, retries, or a dataset changing between calls. A production client must define whether an error discards partial results, how retries interact with cursors, and what telemetry is safe to record.

The page cap also needs an explicit failure path. Reaching it should not quietly return an incomplete catalog that looks successful. I would surface a distinct error, retain enough page-count context for diagnosis, and avoid recording the opaque cursor value unless the application's data policy permits it. A retry should resend the exact cursor associated with the failed page rather than restart and combine two potentially different catalog snapshots.

I would not replace a well-tested SDK paginator just to own more loop code. I would keep the empty-cursor fixture as a regression test around the abstraction my application actually calls. I also would not copy this termination rule into an unrelated REST or GraphQL API without reading that API's contract; some protocols explicitly use empty values as sentinels.

Does your MCP client test a non-null empty cursor, or would its catalog stop after page one?

Happy coding!

.NET 10 NU1015: Fix PackageReference Without Version Restore Failures

Sukhpinder Singh — Sun, 23 Aug 2026 21:00:04 +0000

.NET 10 NU1015 turns a PackageReference without a version into a restore error. I like the stricter default because an unbounded direct dependency can quietly resolve the lowest package version. The catch is that versionless XML is also the correct shape for NuGet Central Package Management (CPM). A mechanical “add Version everywhere” repair can undo the policy your repository intended to enforce.

I use a simple split: first decide who owns the version, then make restore prove the answer.

Why .NET 10 NU1015 stops the build

Before .NET 10, NuGet reported NU1604 when a direct reference had no inclusive lower bound. Restore could continue and select the lowest version available from the configured sources. Starting with .NET 10, the same mistake produces NU1015 and restore fails. Microsoft documents this as a stable behavioral change in the .NET 10 compatibility guidance.

Here is the ambiguous project entry:

<ItemGroup>
  <PackageReference Include="Demo.Greeting" />
</ItemGroup>

If this is a normal direct reference, the project is missing its version. If CPM is active, the project is correct and the version should live elsewhere. The NU1015 diagnostic reference calls out a common failure mode: a project that expected CPM was copied into a location where CPM is disabled or its props file is no longer discovered.

That distinction matters more than silencing the error. It tells me whether the project file or the repository-level package policy is broken.

The timing can be misleading. An SDK upgrade may expose an old direct reference that had always relied on lowest-version resolution, while a repository move may break a previously valid CPM import. I inspect the failing project's evaluated inputs, nearby props files, and recent path changes before editing package metadata. That keeps a restore migration from turning into an accidental package-management migration.

Fix the owner, not only the XML

For a direct reference, I add an explicit version:

<PackageReference Include="Demo.Greeting" Version="2.0.0" />

For CPM, I keep the project reference versionless and put the version in the nearest Directory.Packages.props:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Demo.Greeting" Version="2.0.0" />
  </ItemGroup>
</Project>

NuGet automatically imports only the first Directory.Packages.props it finds while walking up from a project. A nested file can therefore change which policy applies, and a copied project can lose the import completely. The official Central Package Management guide describes both the enabling property and the nearest-file rule.

I check the evaluated project context instead of assuming that a props file somewhere in the repository is active. The two valid outcomes are clear: a direct PackageReference owns its Version, or an active CPM file owns the matching PackageVersion.

Reproduce NU1015 without an external feed

The runnable sample creates a local package feed containing Demo.Greeting versions 1.0.0 and 2.0.0. It then tests three consumers:

BrokenDirect has no version and must fail with NU1015.
FixedDirect pins 2.0.0 on the reference.
CentralManaged leaves the reference versionless and pins 2.0.0 in Directory.Packages.props.

From the sample folder, I run:

dotnet restore .\Verifier\Verifier.csproj
dotnet build .\Verifier\Verifier.csproj -c Release --no-restore
dotnet run --project .\Verifier\Verifier.csproj -c Release --no-build --no-restore

The verifier packs both fixture versions, runs each restore, reads project.assets.json, and executes the repaired projects. The important assertions are not just “restore passed.” Both supported repairs must resolve and run with 2.0.0.

The sample also demonstrates the documented compatibility switch:

dotnet restore .\BrokenDirect\BrokenDirect.csproj `
  -p:SdkAnalysisLevel=9.0.300 `
  -p:TreatWarningsAsErrors=false

That brings back NU1604, and the local feed proves why I do not treat it as the fix: NuGet chooses 1.0.0, the lowest available version. The complete validation and review history is in the merged pull request.

Limits and when I avoid the escape hatch

SdkAnalysisLevel=9.0.300 affects every SDK behavior gated by that level, not only this diagnostic. A warnings-as-errors policy can also promote NU1604 back to a failure. I reserve the switch for short migration diagnostics while I determine who should own the version.

The local-feed sample does not model authenticated sources, source mapping, package lock files, or feed outages. Those controls still matter in a production restore. Its narrower job is to make the ownership decision and resolved version deterministic.

I also would not add Version="0.0.0" merely to make NU1015 disappear. Microsoft documents that value for the unusual case where the lowest version is genuinely intended, but it still produces NU1603 when NuGet resolves a higher available version. Most application dependencies need a deliberate version or an active central policy instead.

For direct references, I pin the intended dependency. For CPM repositories, I verify the import boundary and keep versions centralized. Either way, I leave restore with one explicit owner and a test that checks the resolved graph.

Have you hit NU1015 because a direct version was missing, or because a project silently lost its CPM context?

Happy coding!

.NET 10 JSON Console Logging: Stop Parsing State.Message

Sukhpinder Singh — Sat, 22 Aug 2026 18:47:25 +0000

The .NET 10 JSON console logging change is small enough to miss during an upgrade: the formatted message still exists, but a typical record no longer duplicates it at State.Message. A collector, script, or snapshot test that reads only that nested property can start returning null while the application continues logging normally.

I treat console JSON as a schema whenever another process parses it. That means a runtime upgrade deserves a contract test, not just a visual check in a terminal. The practical fix is to read the top-level Message, keep State for structured values, and retain a narrow fallback for older records.

Why .NET 10 JSON console logging breaks nested-message parsers

Before .NET 10, a normal AddJsonConsole record commonly repeated the rendered text:

{
  "Message": "Order 42 moved to ready.",
  "State": {
    "Message": "Order 42 moved to ready.",
    "OrderId": 42,
    "Status": "ready",
    "{OriginalFormat}": "Order {OrderId} moved to {Status}."
  }
}

In .NET 10, the typical shape keeps one rendered message at the top level:

{
  "Message": "Order 42 moved to ready.",
  "State": {
    "OrderId": 42,
    "Status": "ready",
    "{OriginalFormat}": "Order {OrderId} moved to {Status}."
  }
}

Microsoft documents this as a behavioral breaking change and recommends that parsers use the top-level property. The official compatibility note also gives an essential caveat: State.Message may still appear when its content differs from the top-level value. I therefore do not reject a record merely because both properties exist.

This is not a loss of structured logging data. OrderId, Status, and {OriginalFormat} remain useful fields inside State. The part that changed is where a consumer should get the rendered sentence.

Prefer the top-level Message and keep State structured

A legacy-only extractor is brittle because it assumes the duplicate is the contract:

static string? ReadLegacyOnly(JsonElement root) =>
    root.TryGetProperty("State", out var state) &&
    state.TryGetProperty("Message", out var message)
        ? message.GetString()
        : null;

I use a top-level-first rule instead:

static string? ReadMessage(JsonElement root) =>
    ReadTopLevelMessage(root) ?? ReadStateMessage(root);

The fallback is for stored .NET 9-era records or mixed-version fleets. It is not a reason to keep a new parser anchored to the old nested location. When both values exist and differ, the top-level field stays canonical, matching Microsoft's migration guidance.

I also parse the structured properties separately. Searching a rendered sentence for an order ID throws away the main benefit of JSON logging. The formatter keeps those values addressable under State, while {OriginalFormat} preserves the message template for grouping or diagnostics.

The built-in formatter can be configured with AddJsonConsole; Microsoft's console formatter documentation covers timestamps, scopes, and JSON options. Those options can change other parts of a record, so my contract focuses only on fields the consuming pipeline actually needs.

Turn the schema into an offline regression test

The runnable sample contains a documented legacy fixture, a real .NET 10 emitter, and a verifier. The emitter uses the installed runtime rather than a hand-written “current” fixture:

builder.AddJsonConsole(options =>
{
    options.UseUtcTimestamp = true;
    options.TimestampFormat = "O";
});

var orderMoved = LoggerMessage.Define<int, string>(
    LogLevel.Information,
    new EventId(1001, "OrderMoved"),
    "Order {OrderId} moved to {Status}.");

orderMoved(logger, 42, "ready", null);

The verifier launches that emitter, captures its single JSON line, and checks semantics rather than timestamp text or property order. It proves that the top-level message exists, the redundant nested message is absent for this ordinary case, and the structured values remain intact. It then runs the same compatibility extractor against the legacy fixture.

That test is deterministic and offline after restore. It needs no logging backend, account, credential, or paid service. It also catches a more realistic failure than a unit test built from two hand-authored strings: the current side of the contract comes from AddJsonConsole itself.

I verified the sample with .NET SDK 10.0.303 and runtime 10.0.11; the official 10.0.11 release notes identify that patch as a supported .NET 10 release. The contract change applies to .NET 10 generally, not only that patch.

Limits and when not to parse console JSON

This approach is for consumers that must accept the built-in console formatter's output. A provider, collector, or OpenTelemetry pipeline may expose a different and better-defined schema. I would test that contract directly instead of translating every provider into this shape.

Console JSON is also not an ideal application-to-application protocol. If I control both sides, I prefer a structured transport with explicit versioning. When console output is the available boundary, a small compatibility extractor and fixture set make the assumption visible.

Finally, I would not assert that State.Message can never exist. The official caveat matters. Prefer top-level Message, preserve structured State, and test the specific records your pipeline depends on.

What console log field is your upgrade test still assuming will always be there?

Cheers!

MCP C# SDK Array Tool Outputs: Stop Looking for a `result` Wrapper

Sukhpinder Singh — Fri, 21 Aug 2026 01:23:31 +0000

MCP C# SDK array tool outputs are easy to misread after a protocol upgrade. A client written around the older wire shape may always reach for structuredContent.result. Once both sides negotiate MCP 2026-07-28, an array is an array and a scalar is a scalar. There is no required wrapper to unwrap.

I treat that as a contract change worth testing at the transport boundary. A unit test against the C# return type cannot tell me what tools/list advertised or what tools/call actually carried. The small verifier below runs both protocol versions offline and makes the difference explicit.

The wire contract changed, not just the C# type

The MCP 2026-07-28 tools specification allows structuredContent to contain any JSON value: object, array, string, number, Boolean, or null. An outputSchema may likewise describe an array or primitive at its root. The schema still matters: servers must return content that conforms to it, and clients should validate the result.

This is different from the older object-only convention. Under 2025-11-25, a tool returning string[] needs an object envelope such as this:

{
  "structuredContent": {
    "result": ["starter", "growth", "enterprise"]
  }
}

The modern form is the value itself:

{
  "structuredContent": ["starter", "growth", "enterprise"]
}

The stable MCP C# SDK handles this negotiation. Its v2.0.0 release notes call out direct non-object tool results, while the current v2.2.0 tools guide documents UseStructuredContent. For a down-level client, the SDK still emits the compatibility envelope. I do not need a second handler or a hand-written version switch.

Build two real in-memory protocol sessions

The sample pins the current stable package and targets .NET 10:

<ItemGroup>
  <PackageReference Include="ModelContextProtocol" Version="2.2.0" />
</ItemGroup>

It registers one array tool and one scalar tool. UseStructuredContent = true tells the SDK to generate the output schema and serialize the return value into structuredContent.

toolCollection.Add(McpServerTool.Create(
    (Func<string[]>)ListTiers,
    new McpServerToolCreateOptions
    {
        Name = "list_tiers",
        UseStructuredContent = true,
        ReadOnly = true,
    }));

toolCollection.Add(McpServerTool.Create(
    (Func<int>)CountTiers,
    new McpServerToolCreateOptions
    {
        Name = "count_tiers",
        UseStructuredContent = true,
        ReadOnly = true,
    }));

Two System.IO.Pipelines.Pipe instances connect an McpClient and McpServer. Nothing opens a port and no model is involved, but discovery and calls still cross the SDK's stream transport. I create one pair with McpClientOptions.ProtocolVersion = "2026-07-28" and a fresh pair with "2025-11-25".

Using separate sessions matters. The negotiated protocol belongs to a connection, so changing an option after discovery would not prove the real compatibility path.

Verify MCP C# SDK array tool outputs on the wire

For the modern session, I assert both the advertised schema and the returned value:

JsonElement arraySchema = arrayTool.ProtocolTool.OutputSchema!.Value;
CallToolResult arrayResult = await arrayTool.CallAsync();

Check(arraySchema.GetProperty("type").GetString() == "array");
Check(arrayResult.StructuredContent?.ValueKind == JsonValueKind.Array);
Check(!TryReadLegacyResult(arrayResult.StructuredContent!.Value, out _));

That last check is a deliberate negative control. It models the parser I want to remove: one that only succeeds when the root is an object containing result. If the contract test only checks the values, an accidental wrapper can slip back in unnoticed.

The legacy session checks the opposite shape:

Check(IsLegacyEnvelope(arraySchema, "array"));
Check(
    arrayResult.StructuredContent?
        .GetProperty("result")
        .ValueKind == JsonValueKind.Array);

Both sessions then verify the three tier values and the text content fallback. That fallback is useful for older or text-oriented consumers and is recommended by the specification when structured content is returned.

On the client side, I branch from the discovered schema before reading the result. I do not infer the shape from the tool name or from a C# type in my own codebase; a client may be talking to a server implemented in another language. For an array root, I enumerate the value directly. For the down-level object schema, I read the required result property.

Checking discovery and invocation together also catches an asymmetric bug: a server could advertise an array schema but return a wrapped object, or advertise the legacy envelope and emit a bare array. Either response may contain the expected values while still violating the declared contract. The paired assertions fail on that mismatch before application parsing hides it.

Running the verifier produces a stable summary:

PASS 15/15
  modern: array schema has an array root
  modern: array result has no result wrapper
  modern: legacy result-wrapper parser is rejected
  legacy: array schema advertises a result envelope
  legacy: array result keeps the result envelope

The complete sample on main includes the scalar checks, setup commands, expected output, and vulnerability audit. The associated merged pull request records the exact validation commands and results.

When this test is not enough

This verifier proves the official MCP C# SDK 2.2.0 behavior over its stream transport. It does not prove that every host accepts every JSON Schema 2020-12 construct. A third-party client may lag the protocol, apply a narrower schema profile, or ignore structured content entirely. I would add an end-to-end test for each real host before relying on array or primitive roots in production.

An output schema also checks shape, not business meaning. The tool must still validate inputs, authorization, and domain rules. If every consumer already expects an object with named fields, returning a small response record may be clearer than returning a bare array just because the protocol permits it.

For mixed fleets, I let negotiation select the wire shape and make the client read according to the advertised outputSchema. I avoid hard-coding either a wrapper or a natural root globally.

Which client contract would you add to this compatibility matrix first?

Happy coding!

.NET 10 Numeric String Sorting: Put File 10 After File 9

Sukhpinder Singh — Thu, 20 Aug 2026 16:58:53 +0000

When I display generated filenames, .NET 10 numeric string sorting gives me the order people usually expect: file9.txt before file10.txt. The new CompareOptions.NumericOrdering flag handles digit runs without a handwritten natural-sort parser.

That sounds like a presentation-only change. It is not. The same comparer also decides whether two strings are equal, which can quietly collapse file2.txt and file02.txt inside a set or dictionary. I want both parts of that contract visible before I reuse the comparer across an application.

Why ordinary string order looks wrong

Ordinal comparison reads the characters from left to right. After the shared file prefix, the first digit in file10.txt is 1, so it sorts before the 9 in file9.txt. The comparer is behaving correctly; it simply does not interpret a run of digits as a number.

string[] fileNames =
[
    "file10.txt",
    "file2.txt",
    "file02.txt",
    "file9.txt"
];

var ordinal = fileNames.Order(StringComparer.Ordinal);

That produces this sequence:

file02.txt | file10.txt | file2.txt | file9.txt

Padding every number can work when I control the naming format, but it is brittle for imported files, user-facing labels, and old data. A regex that splits text and numbers is another option, although it creates parsing, allocation, overflow, and edge-case decisions that a simple sort should not need.

.NET 10 numeric string sorting with one comparer

.NET 10 added NumericOrdering as a stable string-comparison option. The official .NET 10 library notes show that digit sequences are compared by numeric value, so 2 comes before 10.

I can package the culture and comparison rule in one StringComparer:

using System.Globalization;

StringComparer numericComparer = StringComparer.Create(
    CultureInfo.InvariantCulture,
    CompareOptions.NumericOrdering);

var numeric = fileNames.Order(numericComparer);
Console.WriteLine(string.Join(" | ", numeric));

The result is:

file2.txt | file02.txt | file9.txt | file10.txt

The sample uses InvariantCulture for reproducible output across machines. For labels shown directly to a person, CurrentCulture may be the better choice. The important part is to choose deliberately rather than inherit an implicit comparison rule.

I also keep this comparer close to the query that needs it. Passing it explicitly to Order makes the display rule reviewable and prevents a natural-sort policy from leaking into unrelated keys. If case should be ignored for a particular UI, CompareOptions.IgnoreCase can be combined with NumericOrdering, but that is another equality decision worth making at the call site.

Natural order also changes equality

StringComparer supplies ordering, equality, and hash codes. With NumericOrdering, leading zeroes do not change the numeric value of a digit run:

Console.WriteLine(
    numericComparer.Equals("file2.txt", "file02.txt"));
// True

var names = new HashSet<string>(numericComparer)
{
    "file2.txt",
    "file02.txt"
};

Console.WriteLine(names.Count);
// 1

That equality is useful when chapter2 and chapter02 are alternate spellings of the same display label. It is destructive when both are real file names that must remain distinct. I use the numeric comparer only at the sorting boundary in that case and keep exact identity under StringComparer.Ordinal or the platform-appropriate file-name rule.

Equal items retain their incoming relative order in the sample, which is why file2.txt stays ahead of file02.txt. I do not treat input order as a meaningful tie-breaker. If the output must be reproducible after inputs arrive in a different order, I add an explicit ordinal secondary key while leaving identity comparisons separate.

Punctuation deserves the same care. The CompareOptions reference says a decimal point, minus sign, plus sign, or any other non-digit ends the digit sequence. As a result, v1.5 and v1.05 compare as equal: each digit run is compared independently. This is natural collation, not decimal or semantic-version parsing.

Verify the contract, not just the screen

The runnable sample on main turns these details into six deterministic checks. It has no package dependencies, credentials, network calls, or generated test data.

dotnet restore
dotnet format NumericStringSorting.csproj --verify-no-changes --no-restore
dotnet build NumericStringSorting.csproj -c Release --no-restore
dotnet run --project NumericStringSorting.csproj \
  -c Release --no-build -- --verify

The verifier checks ordinal and numeric order, leading-zero equality, HashSet deduplication, punctuation behavior, and the rejection of NumericOrdering by index-based operations. A successful run ends with PASS 6/6. The merged sample pull request also records the exact validation commands.

When I would not use NumericOrdering

I would not use this comparer to parse signed numbers, decimals, dates, or semantic versions. Those domains need parsers that understand their grammar. I also would not use it for IndexOf, StartsWith, EndsWith, and related search operations; NumericOrdering is not valid for those APIs.

Most importantly, culture-aware collation should not decide authentication, authorization, protocol identifiers, or other security-sensitive equality. Microsoft's string comparison guidance recommends ordinal rules for non-linguistic and security comparisons.

For a visible list containing embedded positive integers, though, the new comparer removes a surprising amount of custom code. I just keep its equality semantics close enough that nobody mistakes natural order for exact identity.

What would you sort with NumericOrdering first: filenames, build labels, or something else?

Happy coding!

MCP C# SDK Hybrid Sessions: Serve Old and New Clients on One Endpoint

Sukhpinder Singh — Wed, 19 Aug 2026 18:47:30 +0000

The MCP C# SDK hybrid sessions option solves an awkward upgrade boundary: some clients still use the 2025-11-25 initialize handshake and depend on sessions, while clients on 2026-07-28 expect every HTTP request to stand alone. I want both groups to reach one ASP.NET Core endpoint without making modern clients downgrade or stripping useful behavior from legacy clients.

The stable C# SDK 2.2.0 release added exactly that path with HttpServerSessionMode.StatefulForInitializeClients. The release notes describe it as hybrid stateful/stateless serving, and the official session-mode guide spells out the per-request behavior.

Why one global session switch fails

The 2026-07-28 MCP revision removed the initialize handshake and Mcp-Session-Id from its wire format. Client identity, capabilities, and protocol version travel with each request instead. The final specification announcement explains why the core moved toward request/response statelessness.

That creates a migration choice for an existing server.

With HttpServerSessionMode.Stateful, initialize-era clients receive full sessions. A modern request is refused so a dual-path client can fall back to the older handshake. Compatibility is preserved, but the client does not use the new protocol natively.

With HttpServerSessionMode.Stateless, every request is independent. That is the right default for servers that do not need session state, unsolicited notifications, resource subscriptions, or older server-to-client flows. It may be too abrupt when deployed clients still rely on those features.

Hybrid mode makes the decision from the incoming request instead of applying one choice to the endpoint.

Configure MCP C# SDK hybrid sessions

The server configuration is deliberately small:

builder.Services
    .AddMcpServer()
    .WithHttpTransport(options =>
    {
        options.SessionMode =
            HttpServerSessionMode.StatefulForInitializeClients;
    })
    .WithTools<DemoTools>();

app.MapMcp("/mcp");

An initialize-era client sends an initialize request with protocolVersion: "2025-11-25". The server returns Mcp-Session-Id, and that client must send the value on its later requests.

A 2026-07-28 client sends server/discover or another operation with its modern metadata. It does not receive a session ID:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "hybrid-probe",
        "version": "1.0.0"
      }
    }
  }
}

For Streamable HTTP, the request also carries MCP-Protocol-Version: 2026-07-28 and the routing header Mcp-Method: server/discover. Tool calls add Mcp-Name. Those headers do not create a session; they let the transport route and validate a self-describing request.

Prove both protocol eras with TestServer

Configuration alone is easy to regress. I prefer a transport-level check that exercises the real SDK handler while staying offline.

The complete sample uses Microsoft.AspNetCore.TestHost, so it opens no port and calls no model. Its verifier runs these checks against the same /mcp route:

Modern discovery succeeds and returns no Mcp-Session-Id.
A modern echo tool call succeeds and remains stateless.
Legacy initialize succeeds and mints a non-empty session ID.
The legacy notification and tool call reuse that session.
Modern DELETE returns 405 Method Not Allowed.
Legacy DELETE closes its session successfully.

The assertion that matters is not just a 200 response. Each side must get the correct session semantics:

AssertNoSession(modernToolCall, "modern tool call");

string sessionId = GetRequiredSessionId(
    legacyInitialize,
    "legacy initialize");

Equal(
    sessionId,
    GetRequiredSessionId(legacyToolCall, "legacy tool call"));

Run the verifier with:

dotnet restore .\McpHybridSessions.csproj
dotnet build .\McpHybridSessions.csproj -c Release --no-restore
dotnet run --project .\McpHybridSessions.csproj -c Release --no-build

The merged implementation and validation record are also in the pull request.

Limits and when not to use hybrid mode

Hybrid mode is a bridge, not a new universal default. If every supported client speaks 2026-07-28 and the server needs no session-only behavior, choose Stateless. It is simpler to scale because requests can land on any instance without affinity.

The modern half of a hybrid endpoint is still stateless. It cannot receive unsolicited notifications or use resource subscriptions, and it does not gain per-client isolation. Use the newer multi-round-trip mechanism where it fits rather than assuming hybrid mode restores sessions for modern requests.

The legacy half still has the operational costs of sessions. Session memory lives on the server, restarts discard it, and multiple instances may need affinity or a deliberate migration design. Authentication and authorization are separate concerns; a session ID is not proof of identity.

I would keep this regression test until the last initialize-era client is retired, then change the server and test together to the explicit stateless mode.

Are you keeping a legacy session path during your 2026-07-28 migration, or can your server go fully stateless?

Happy coding!

MCP x-mcp-header Validation: Keep Bad Tool Schemas Out of tools/list

Sukhpinder Singh — Wed, 19 Aug 2026 18:33:55 +0000

MCP x-mcp-header validation is easy to miss because the annotation looks like ordinary JSON Schema metadata. On the 2026-07-28 Streamable HTTP transport, it is a wire contract: the client copies selected tool arguments into Mcp-Param-* headers, intermediaries can act on those headers, and the server checks them against the JSON-RPC body.

I treat that contract as something to test before a tool reaches tools/list. A bad suffix, an unsupported type, or an unreachable annotation makes the whole tool definition invalid. Silently accepting it only moves the failure to a harder place to diagnose.

Why the same value travels twice

The final Streamable HTTP specification mirrors request metadata into HTTP headers so a load balancer, gateway, or WAF does not need to parse JSON-RPC. A server can add x-mcp-header to a tool property:

{
  "type": "object",
  "properties": {
    "region": {
      "type": "string",
      "x-mcp-header": "Region"
    }
  }
}

A call with "region": "us-west1" then carries:

Mcp-Param-Region: us-west1

The official C# SDK can generate that schema from a parameter attribute:

[McpServerTool]
public static string ExecuteSql(
    [McpHeader("Region")] string region,
    string query) => $"Queued for {region}";

Current C# SDK v2 tool documentation describes both schema generation and automatic header projection. The feature is on the stable v2 line; it is not necessary to pin an earlier preview or release candidate.

MCP x-mcp-header validation rules

The final tool definition rules are deliberately narrow.

The annotation value must be a non-empty HTTP field-name token and must be unique without regard to case. Region and region therefore collide. Control characters, spaces, and separators such as a colon are not valid suffix characters.

Only string, integer, and boolean properties can be mirrored. JSON Schema number is excluded, and integer values must stay between -(2^53 - 1) and 2^53 - 1 so every conforming implementation can represent the value exactly.

Reachability is the rule most likely to surprise me. An annotated property can be nested, but the path from the schema root must pass only through properties. An annotation below items, $ref, oneOf, allOf, if, or another composition or conditional keyword is invalid. A Streamable HTTP client must exclude an invalid tool from the returned tools/list result and should log the reason. A stdio client may ignore these annotations because it has no HTTP headers to project.

Values have their own encoding rules. Plain visible ASCII can travel as-is. Non-ASCII text, control characters, leading or trailing whitespace, and strings that already look like the =?base64?...?= sentinel must be UTF-8/Base64 encoded inside that sentinel. Boolean values become lowercase true or false; mathematically integral JSON forms such as 42.0 normalize to decimal 42. If an optional argument is absent or explicitly null, the client omits its header.

Make schema drift fail offline

The sample draft PR turns those requirements into a dependency-free .NET 10 executable. It scans the relevant JSON Schema subschema locations, ignores annotation-shaped literal data under keywords such as default, records valid property paths, and fails malformed schemas before any network request.

using JsonDocument schema = JsonDocument.Parse(schemaJson);
using JsonDocument arguments = JsonDocument.Parse(argumentJson);

var headers = McpHeaderProjector.Project(
    schema.RootElement,
    arguments.RootElement);

The deterministic verifier covers twelve cases, including nested primitive properties, absent and null arguments, non-ASCII and sentinel encoding, case-insensitive duplicates, the forbidden number type, annotations below items and oneOf, literal example data, invalid HTTP tokens, integral exponent notation, and both safe-integer boundaries.

I like this style of test because it catches two different regressions. A server refactor can accidentally move an annotation behind a $ref; a client refactor can stop encoding a padded or Unicode value. Both changes compile, but both break the transport contract.

At runtime, the server has another job. It must decode recognized Mcp-Param-* values and compare them with the body. A missing, malformed, or different value is HTTP 400 with JSON-RPC error -32020 (HeaderMismatch). When that mismatch suggests a stale schema, the client should refresh tools/list before retrying with the new definition.

Limits: routing metadata is not authorization

These headers help infrastructure route, meter, and observe requests. They do not prove that a caller may use the region, tenant, or resource named in the value. An attacker who can choose the body can usually choose the matching header too, so the application still needs normal authentication and authorization checks. A gateway enforcing policy on mirrored headers should reject an absent or older protocol version, where header/body validation is not guaranteed.

I would never mark a password, API key, access token, or personally identifiable value with x-mcp-header. Base64 is only an encoding, and headers are visible to intermediaries and often copied into logs.

The sample is also a focused conformance fixture, not a full JSON Schema 2020-12 engine or a replacement for the official SDK. Its value is keeping the sharp transport rules visible in tests. For production, use a current SDK, validate header/body equality on the server, and keep authorization tied to the authenticated principal.

Which malformed schema or encoding edge case would you add to this regression set?

Happy coding!