DEV Community: Sukhpinder Singh

MCP Python SDK Extension Method Collisions: Fail Before the Server Starts

Sukhpinder Singh — Thu, 10 Sep 2026 23:09:06 +0000

MCP Python SDK extension method collisions are configuration defects, not runtime edge cases. If two extensions claim the same method—or one claims a core MCP method—the server should reject that setup before it accepts a request. I prefer making method ownership an executable contract so registration order can never decide which handler wins.

The official MCP Python SDK extension documentation defines three useful safeguards: core methods cannot be registered as extension methods, duplicate extension methods are rejected during registration, and every binding must declare at least one supported protocol version.

Why collisions should fail during startup

An extension adds vendor-specific behavior to the same dispatch table used by the rest of the server. That makes method names part of the server's public contract.

Consider two independently configured extensions that both expose:

com.example/catalog.search

A last-write-wins registry would make the active handler depend on extension order. Reordering configuration could silently change request behavior without changing the client call.

The safer contract is one owner per method name. In the sample, a valid extension starts normally, while a second extension claiming the same method causes MCPServer construction to raise ValueError.

Core protocol methods have an even stronger boundary. A vendor extension must not replace methods such as tools/list. The SDK's MCP extension core method guard rejects that binding when MethodBinding is constructed.

The sample targets protocol version 2026-07-28, announced in the project's final MCP release post, and pins the stable mcp==2.1.1 package so the checks are reproducible.

Build a version-pinned `MethodBinding`

I start with a namespaced method and an explicit protocol-version set:

PROTOCOL_VERSION = "2026-07-28"
EXTENSION_ID = "com.example/catalog"
METHOD = "com.example/catalog.search"


def search_binding(method: str = METHOD) -> MethodBinding:
    return MethodBinding(
        method,
        SearchParams,
        search,
        protocol_versions=frozenset({PROTOCOL_VERSION}),
    )

The reverse-domain prefix keeps the vendor method separate from core MCP names. More importantly, protocol_versions states exactly where the binding is reachable.

That protocol version validation prevents a subtle configuration mistake. An empty set describes a method that cannot be used under any protocol version, so the SDK rejects it immediately:

def build_unreachable_binding() -> MethodBinding:
    return MethodBinding(
        METHOD,
        SearchParams,
        search,
        protocol_versions=frozenset(),
    )

The valid extension returns one binding:

class CatalogSearch(Extension):
    identifier = EXTENSION_ID

    def methods(self) -> Sequence[MethodBinding]:
        return [search_binding()]

A second extension deliberately returns the same method name:

class ShadowSearch(Extension):
    identifier = "com.example/catalog-shadow"

    def methods(self) -> Sequence[MethodBinding]:
        return [search_binding()]

Neither class is inherently invalid in isolation. The collision appears when both are registered with one server:

MCPServer(
    "extension-contract",
    extensions=[CatalogSearch(), ShadowSearch()],
)

This is the MethodBinding duplicate-method boundary I want to test: the server registry sees two owners and refuses to start.

Checking this boundary during construction keeps the failure close to the configuration that caused it. A deployment never reaches the point where the first unlucky request discovers an ambiguous handler. It also makes the regression test independent of extension ordering: swapping the two classes cannot turn the failure into success. In a larger server, I would keep these ownership tests beside the composition root where optional packages are assembled.

Verify MCP Python SDK extension method collisions offline

The runnable sample checks one valid path and three invalid configurations. Its valid case uses the SDK's in-memory client, so it does not open a port or require an external MCP host:

server = build_valid_server()

async with Client(
    server,
    extensions=[advertise(EXTENSION_ID)],
) as client:
    request = SearchRequest(params=SearchParams(query="mcp"))
    result = await client.session.send_request(
        request,
        SearchResult,
    )

The handler returns deterministic values:

["mcp-0", "mcp-1"]

The positive request is as important as the rejection cases. It proves the namespaced method remains callable when it has one owner, the client advertises the extension identifier, and the typed result survives the same registry being guarded. Without that control case, a test could pass simply because every extension path was broken.

The remaining checks construct a duplicate server, attempt to bind tools/list, and create a binding with an empty version set. The verifier catches ValueError only to assert the boundary; production startup should let those errors stop the process.

Run the full validation with:

uv sync --all-groups
uv lock --check
uv run ruff format --check .
uv run ruff check .
uv run mypy extension_contract.py verify.py test_extension_contract.py
uv run python -m compileall -q extension_contract.py verify.py test_extension_contract.py
uv run python -m unittest -v
uv run python verify.py
uv run pip-audit

The deterministic verifier reports:

[PASS] unique vendor method starts normally
[PASS] typed request keeps the vendor method
[PASS] duplicate method fails during server construction
[PASS] core MCP method cannot be claimed
[PASS] empty protocol version set is rejected
5/5 checks passed

The merged changes and validation record are also available in the sample pull request.

Limitations and when not to use this pattern

This sample verifies construction and in-memory request dispatch. It does not test stdio, Streamable HTTP, authentication, extension result claims, or notification bindings.

It also pins exact exception-message fragments for SDK 2.1.1. If I were supporting several SDK releases, I would make the exception type and offending method the durable assertions, then keep message checks narrow enough to tolerate wording changes.

These checks are most useful when a server composes extensions from multiple packages or configuration sources. For a small server with no extensions, the extra contract tests may add little value. They also complement integration tests rather than replacing transport and authorization coverage.

How are you testing extension method ownership before your MCP server accepts traffic?

Happy building!

.NET 10 Generic Math Shift Masking: Catch Overshifts That Now Wrap

Sukhpinder Singh — Tue, 08 Sep 2026 22:13:40 +0000

.NET 10 generic math shift masking changes the result of some oversized shifts on small integer types. If a helper uses IShiftOperators<T, int, T>, code such as a generic byte << 8 can return 1 on .NET 10 where it returned 0 on .NET 9. That is a narrow behavioral change, but it can matter in bit-field parsing, binary protocols, compact identifiers, and any test fixture that treats an out-of-range count as an implicit zero.

I treat this as a contract problem. The runtime now behaves consistently; the application still has to decide whether an oversized count is valid.

Why .NET 10 generic math shift masking changes results

The official breaking-change note says generic shifts now mask the shift amount as appropriate for all built-in integer types. The affected small types are byte, char, sbyte, short, and ushort, and the affected operators are <<, >>, and >>>.

This is specifically about operators dispatched through generic math. A concrete C# expression involving a byte can be promoted to int; a generic method constrained by IShiftOperators<T, int, T> returns T. That distinction is why a normal happy-path unit test may not reveal the upgrade boundary.

Here is the core of the reproducer:

static T ShiftLeft<T>(T value, int count)
    where T : IShiftOperators<T, int, T> => value << count;

static T UnsignedShiftRight<T>(T value, int count)
    where T : IShiftOperators<T, int, T> => value >>> count;

The generic math guide explains the static interface-member model behind these constraints. The syntax did not change here. The built-in implementations did.

Reproduce the .NET 9 and .NET 10 boundary

The runnable sample multi-targets net9.0 and net10.0, then runs the same cases under both installed runtimes. It checks counts equal to the type width and one greater than the width. It also includes int << 32 as a control because int already masks its shift count.

The relevant output is deliberately small:

.NET 9:  byte-left-8=0, byte-left-9=0
.NET 10: byte-left-8=1, byte-left-9=2

.NET 9:  byte-unsigned-right-8=0
.NET 10: byte-unsigned-right-8=128

both:    int-left-32-control=1

For the .NET 10 byte cases, a count of 8 becomes 0 after masking, and 9 becomes 1. The value is therefore shifted by zero or one position. The .NET 9 result reflected the previous inconsistent small-integer behavior.

The count is not clamped to the largest legal position. It is reduced according to the operand width, so every additional full width repeats the same positions. That makes 8, 16, and 24 equivalent counts for an eight-bit implementation. It also explains why an overshift may produce a nonzero value rather than clearing all bits. Tests should assert the domain rule, not a vague expectation that a “large enough” shift becomes zero.

For an upgrade audit, I search for IShiftOperators, IBinaryInteger, generic <</>> helpers, and methods that accept an unvalidated count. I then prioritize small built-in types. Calls whose count is a compile-time constant below the width are not affected; input-derived counts, sentinels equal to the width, and reusable bit-packers deserve the cross-runtime test. Searching only for byte << misses helpers where T hides the eventual operand type.

The verifier builds both targets, requires the exact output, and fails on any unexpected exit code. It has no package references and needs no credentials, clock, random input, or network call at runtime. The associated sample pull request records the complete validation commands and results.

Make the shift-count policy explicit

Runtime consistency is useful, but silent normalization is not always the right application rule. I prefer to name one of two policies at the boundary.

For a protocol offset or serialized bit index, reject a count outside the value width:

static T ShiftLeftReject<T>(T value, int count, int width)
    where T : IShiftOperators<T, int, T>
{
    ArgumentOutOfRangeException.ThrowIfNegative(count);
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width);

    if (count >= width)
        throw new ArgumentOutOfRangeException(nameof(count));

    return value << count;
}

For a domain where cyclic counts are intentional, normalize them yourself:

static T ShiftLeftModulo<T>(T value, int count, int width)
    where T : IShiftOperators<T, int, T>
{
    ArgumentOutOfRangeException.ThrowIfNegative(count);
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width);
    return value << (count % width);
}

With the matching built-in value width, both versions behave the same on .NET 9 and .NET 10. More importantly, a reviewer can see the policy without knowing a runtime-specific operator rule.

Keep width close to the numeric type rather than accepting an unrelated caller-provided value. In a reusable library, a type-specific helper or a small metadata table is clearer than letting every call site guess. The sample passes the width explicitly so the two policies remain visible, testable, and easy to adapt.

When not to use modulo masking

Do not add % width simply to preserve the new output. If an oversized count signals corrupt input, masking turns an invalid value into a plausible one. Rejection is usually safer for parsers, authorization bitsets, storage formats, and externally supplied offsets.

This sample also does not define semantics for custom numeric types; their operator implementations remain their own contracts. Review rotations, sign extension, negative counts, and cryptographic code separately. A shift verifier can expose a changed result, but it cannot decide whether that result is correct for the domain.

.NET 10 is a stable LTS release, and the current 10.0.11 release notes list the SDK/runtime builds used for this check. If your library targets multiple runtimes, I would keep the cross-target assertion until the oldest affected target leaves support.

Would your code reject an oversized shift count, or is modulo behavior part of its contract?

Happy coding!

EF Core 10 Named Default Constraints: Preview the Migration SQL Before Deploying

Sukhpinder Singh — Thu, 03 Sep 2026 19:35:34 +0000

EF Core 10 named default constraints solve an annoying SQL Server maintenance problem: database-generated names such as DF__Jobs__Status__... are hard to predict in scripts and incident playbooks. The new convention gives every default a stable name. The catch is easy to miss: enabling it on an existing model makes the next migration change every default constraint in that model.

That is exactly the kind of small configuration edit that deserves a migration gate. I want to know how many columns will change, what SQL will run, and whether the preview can be checked without pointing a tool at a real database.

Why EF Core 10 named default constraints can surprise CI

EF Core 10 adds two naming choices for SQL Server defaults. I can pass a name directly to HasDefaultValue or HasDefaultValueSql, or enable the global convention:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.UseNamedDefaultConstraints();

    modelBuilder.Entity<Job>(entity =>
    {
        entity.Property(job => job.Status)
            .HasDefaultValue("queued");
        entity.Property(job => job.CreatedUtc)
            .HasDefaultValueSql("SYSUTCDATETIME()");
        entity.Property(job => job.RetryCount)
            .HasDefaultValue(0);
    });
}

The generated names are predictable: DF_Jobs_Status, DF_Jobs_CreatedUtc, and DF_Jobs_RetryCount. Predictability helps when a deployment script, DBA, or rollback procedure must refer to a constraint.

The global call is not metadata-only for an existing schema. Microsoft’s EF Core 10 release notes warn that the next migration renames every default constraint in the model. A build that only checks whether migrations compile will not show the scope clearly.

Preview the migration SQL without SQL Server

I built the runnable sample around two committed migrations. InitialSchema represents the old model with three unnamed defaults. NameDefaultConstraints is scaffolded after adding the global convention.

The second migration contains three AlterColumn operations. Each operation keeps the same CLR type and default value, but adds the relational annotation:

migrationBuilder.AlterColumn<string>(
    name: "Status",
    table: "Jobs",
    type: "nvarchar(32)",
    maxLength: 32,
    nullable: false,
    defaultValue: "queued",
    oldClrType: typeof(string),
    oldType: "nvarchar(32)",
    oldMaxLength: 32,
    oldDefaultValue: "queued")
    .Annotation(
        "Relational:DefaultConstraintName",
        "DF_Jobs_Status");

Generating a migration script does not require a live connection. The SQL Server provider can translate the committed operations locally:

dotnet tool restore
dotnet restore
dotnet build -c Release --no-restore
dotnet tool run dotnet-ef migrations script `
  InitialSchema NameDefaultConstraints `
  --no-build --configuration Release

The preview reveals more than the C# migration name suggests. For every affected column, EF queries sys.default_constraints to discover the opaque old name, drops that constraint, alters the column, and adds the predictable constraint. In this sample that sequence happens three times. The script does not drop a table or column, but it is still schema work worth reviewing for locks and deployment duration.

Turn the migration preview into a deterministic gate

Reading a script once is useful; making the expectation executable is better. The sample resolves EF’s migrations services without opening the placeholder connection. It inspects the second migration and then generates the upgrade SQL twice from fresh contexts:

var alteredDefaults = namingMigration.UpOperations
    .OfType<AlterColumnOperation>()
    .ToArray();

Check(alteredDefaults.Length == 3,
    "enabling the convention changes all three defaults");

Check(CountOccurrences(sql, "DROP CONSTRAINT") == 3,
    "SQL drops all three existing default constraints");

The verifier also checks the three exact DF_... names, confirms three lookups in sys.default_constraints, rejects DROP TABLE and DROP COLUMN, and confirms the placeholder connection remains closed. Five repeated runs produce identical output. The complete commands and expected nine checks are in the sample README, and the merged pull request preserves the reviewed diff.

For CI, I prefer these semantic assertions over a snapshot of the entire SQL file. Provider patches may adjust whitespace, batch separators, or local variable names without changing the operation. Counting the affected defaults and checking the exact new constraint names keeps the gate focused. If a fourth default is added later, the test fails deliberately and asks the reviewer to update the expected scope instead of accepting a wider migration by accident.

This is intentionally a contract test, not an integration test. It answers “what does this migration plan to do?” without requiring SQL Server, credentials, or a disposable database. I would still apply the migration to a representative database before production because an offline script cannot predict lock duration, workload contention, or provider permissions. Microsoft’s migration management guidance makes the same broader point: generated migrations should be reviewed and customized when needed.

When I would avoid the global convention

UseNamedDefaultConstraints() is convenient for a new schema because the names exist from the first migration. It is also reasonable for a small existing schema when the generated changes have been reviewed and scheduled.

For a large or busy database, I would consider a staged rollout. EF Core 10’s UseNamedDefaultConstraints API is SQL Server-specific, and the property-level overloads let me name selected defaults first. That keeps an unrelated model edit from producing a broad migration.

I would also avoid treating the operation count as a performance estimate. Three safe-looking changes in a demo say nothing about hundreds of defaults on hot production tables. The gate protects scope and intent; database rehearsal protects the rollout.

Would you enable named defaults globally, or introduce explicit names one property at a time?

Happy coding!

OpenAI Responses API previous_response_id Instructions: Repeat Policy on Every Turn

Sukhpinder Singh — Thu, 03 Sep 2026 02:30:51 +0000

OpenAI Responses API previous_response_id instructions have a counterintuitive boundary: the response ID carries conversation state forward, but it does not carry the prior top-level instructions. If my application uses that field for output format, tool rules, or safety constraints, turn two can quietly run without the policy I expected.

I prefer to make that boundary visible in request construction. A small guard can require instructions on every policy-bound turn, while still allowing the application to replace them deliberately.

Why OpenAI Responses API previous_response_id instructions disappear

The Responses API supports several state strategies. With previous_response_id, a new response can continue from an earlier one without resending the full conversation. OpenAI's conversation state guide shows that chaining pattern directly.

That convenience does not make every request option persistent. The create response reference says that earlier instructions are not carried into a request that uses previous_response_id. The new request can supply the same instructions, different instructions, or none.

This is useful when I want to change behavior mid-thread. It is risky when the omission is accidental.

Consider an application that expects every answer to follow a JSON contract:

const string Policy =
    "Answer in JSON with keys summary and risks.";

var first = new
{
    model = "gpt-5.6",
    instructions = Policy,
    input = "Review the deployment plan.",
    store = true
};

A continuation that sends only the new input and the earlier response ID has conversation context, but not that top-level policy. I therefore build the second turn with the policy beside the continuation ID:

var second = new
{
    model = "gpt-5.6",
    instructions = Policy,
    input = "Now focus on rollback.",
    store = true,
    previous_response_id = firstResponseId
};

The distinction is simple: response lineage and request instructions solve different problems. I do not treat one as an implied copy of the other.

Make the continuation contract explicit

I encode the rule in one request builder instead of relying on every call site to remember it. The builder accepts the model, input, instructions, and one optional state reference:

internal sealed record ResponsesTurn(
    string Model,
    string Input,
    string Instructions,
    string? PreviousResponseId = null,
    string? ConversationId = null);

The guard rejects blank instructions before any transport code runs:

ArgumentException.ThrowIfNullOrWhiteSpace(turn.Model);
ArgumentException.ThrowIfNullOrWhiteSpace(turn.Input);
ArgumentException.ThrowIfNullOrWhiteSpace(turn.Instructions);

This is an application invariant, not an API requirement. The API's instructions field is optional. My builder makes it mandatory because this particular application says every turn must carry policy.

I also reject a payload that combines previous_response_id with conversation:

if (turn.PreviousResponseId is not null &&
    turn.ConversationId is not null)
{
    throw new InvalidOperationException(
        "previous_response_id and conversation cannot be sent together.");
}

That mirrors the documented request contract and keeps the state strategy unambiguous. If I decide to move from response chaining to a durable Conversation object, I make that a deliberate code change rather than emitting both fields and waiting for an HTTP 400.

Verify the chained payload offline

The merged sample on main is a dependency-free .NET 10 executable. It builds three fixed payloads: a first turn, a continuation that repeats the policy, and a continuation that intentionally replaces it.

Its verifier checks seven behaviors. It confirms that the first request carries instructions and store: true; the chained request carries both the policy and its fixture response ID; replacement instructions survive serialization; blank instructions and IDs fail locally; the two state mechanisms cannot be combined; and identical inputs produce byte-identical JSON.

The merged pull request records the exact validation commands and results. Restore, formatting, Release build, package inventory, and vulnerability audit pass. Five repeated verifier runs produce identical output. No account, API key, paid request, or model call is needed.

I like this test because it validates the part my code controls. A model call would add latency and output variability without proving that every future call site constructs the payload correctly. The offline fixture makes omission a deterministic build failure.

Limits and when not to use this guard

This sample is not an OpenAI SDK replacement. It writes a narrow JSON shape with string input, sets store: true, and stops before HTTP. A production integration should use a current supported SDK or a complete HTTP client, handle API errors, and test its actual serialization boundary.

The guard also does not fit every state strategy. With store: false, I need to replay the relevant returned items instead of chaining a stored response. A durable Conversation object has its own lifecycle and cannot be combined with previous_response_id. Stored response objects also have retention and token-billing implications described in the conversation state guide, so state selection deserves an explicit product decision.

Finally, model instructions are not authorization. I still enforce permissions, tenant boundaries, validation, and destructive-action checks in application code. Repeating policy keeps the model request consistent; it does not turn prose into a security boundary.

What invariant would you add before a chained request leaves your code?

Happy coding!

.NET 10 InlineArray Explicit Size: Fix TypeLoadException with a Wrapper

Sukhpinder Singh — Wed, 02 Sep 2026 02:49:54 +0000

.NET 10 InlineArray explicit Size is a small compatibility change with an unusually late failure mode. A project can compile, start normally, and then throw TypeLoadException when the runtime first loads a legacy value type that combines InlineArrayAttribute with StructLayoutAttribute.Size.

I would not fix this by deleting the size blindly. The explicit byte count probably represented an interop assumption, so the safer job is to identify what the size meant and move that layout intent to an unambiguous wrapper.

The complete runnable sample creates the invalid metadata in memory, proves that .NET 10 rejects it, and verifies two supported replacements without a native library or external service.

Why the loader rejects the old shape

An inline array already defines its storage: the runtime repeats the struct's single field for the length supplied to InlineArrayAttribute. This declaration therefore describes eight consecutive int values:

[InlineArray(8)]
struct Int8InlineArray
{
    private int _element0;
}

On a normal .NET 10 target, that type occupies 32 bytes. Adding a second size declaration to the same type creates two competing descriptions of its layout:

[InlineArray(8)]
[StructLayout(LayoutKind.Sequential, Size = 32)]
struct LegacyInt8InlineArray
{
    private int _element0;
}

Microsoft documents this as a .NET 10 binary compatibility change. Earlier runtimes allowed implementation-specific behavior. .NET 10 rejects the combination when the type is loaded because any interpretation of the duplicate size information would be ambiguous.

That timing matters. This is not necessarily a compiler diagnostic in source you control. The shape can already exist in a referenced assembly, and a cold path involving reflection, interop registration, or serialization might be the first code that forces the type to load.

Reproduce the TypeLoadException safely

I wanted the sample to demonstrate the loader rule without committing an intentionally broken assembly. It uses Reflection.Emit to create the old metadata at runtime:

var type = module.DefineType(
    "LegacyInt8InlineArray",
    TypeAttributes.NotPublic |
        TypeAttributes.Sealed |
        TypeAttributes.SequentialLayout,
    typeof(ValueType),
    PackingSize.Unspecified,
    typesize: 32);

var constructor = typeof(InlineArrayAttribute)
    .GetConstructor([typeof(int)])!;

type.SetCustomAttribute(new CustomAttributeBuilder(constructor, [8]));
type.DefineField("_element0", typeof(int), FieldAttributes.Private);
_ = type.CreateTypeInfo(); // TypeLoadException on .NET 10

The verifier catches the exception and checks its type. It then uses Unsafe.SizeOf<T>() and fixed values to prove that each replacement is 32 bytes and still supports all eight indexed values. Running the check repeatedly produces identical output, so it works well as an upgrade regression test.

There is a useful testing detail here: keep the invalid shape behind an isolated loader boundary. If I referenced a broken type directly throughout the test executable, the runtime could force it while compiling a method, before the assertion reached its intended try block. Emitting one fixture keeps the failure local and makes the expected exception part of the test result instead of a process-level surprise.

The InlineArrayAttribute documentation is useful context here: the attribute represents sequentially replicated storage. It should be the only mechanism defining the inline array's total repeated shape.

Fix .NET 10 InlineArray explicit Size with a wrapper

The correct replacement depends on the original intent.

If 32 bytes describes the whole native buffer, wrap the inline array and put Size on the outer type:

[InlineArray(8)]
struct Int8InlineArray
{
    private int _element0;
}

[StructLayout(LayoutKind.Sequential, Size = 32)]
struct WholeArrayWrapper
{
    public Int8InlineArray Values;
}

If the explicit size describes one native element, move it to the element and let the inline array repeat that type:

[StructLayout(LayoutKind.Sequential, Size = 4)]
readonly struct SizedElement(int value)
{
    public int Value { get; } = value;
}

[InlineArray(8)]
struct SizedElementArray
{
    private SizedElement _element0;
}

This separation makes the contract reviewable: InlineArray(8) owns repetition, while StructLayout.Size owns either the wrapper boundary or an individual element. The StructLayout size reference also warns that an explicit size must be at least as large as the type's fields.

What I would gate during an upgrade

I would start by scanning source and generated interop code for types that contain both attributes. Then I would load every relevant plugin or interop assembly in a .NET 10 test process, because a successful build does not prove that every value type can be loaded.

That load test should use the same deployment shape as production. Trimming, ahead-of-time compilation, plugin discovery, and architecture-specific assemblies can force types in a different order from a normal developer run. I would also make the test enumerate known boundary types explicitly; waiting for incidental application coverage can leave a rarely used native message or device structure unchecked.

For each hit, I would record whether the byte count belongs to the element, the repeated buffer, or an enclosing native record. After moving the attribute, I would keep three checks close to the boundary:

the managed size is the expected fixed value;
representative values survive indexed reads and writes; and
the real native declaration agrees on field order, packing, and alignment.

The sample and its merged pull request cover the first two checks. They do not prove a platform-specific ABI, and Reflection.Emit is only a controlled way to exercise the loader rule. If the type crosses a P/Invoke boundary, test against the actual native library and every supported architecture. If no native or serialized contract depends on an explicit byte count, a plain inline array may be all you need.

How are you auditing layout-sensitive types before your .NET 10 rollout?

Happy coding!

.NET 10 LDAP VlvRequestControl Validation: Stop Sending Replacement Bytes

Sukhpinder Singh — Tue, 01 Sep 2026 17:59:10 +0000

When I audit an LDAP migration, .NET 10 LDAP VlvRequestControl validation is the kind of small compatibility change I want covered by a focused test. On .NET 9, an unpaired UTF-16 surrogate in a virtual-list-view target can be encoded as the UTF-8 replacement sequence EF BF BD. On .NET 10, the same malformed target is rejected with EncoderFallbackException before LDAP I/O.

That stricter behavior is safer because a client no longer sends bytes that differ from the string it was given. It is still a breaking change if an application has been allowing malformed strings to reach VlvRequestControl.

Why .NET 10 LDAP VlvRequestControl validation matters

LDAP virtual list view controls let a client request a window around a target in a sorted result set. The VlvRequestControl API accepts that target as a .NET string, which must be converted from UTF-16 to UTF-8 when the control value is serialized.

A valid surrogate pair represents one Unicode scalar value and should encode normally. A lone high surrogate such as \uD800, or a lone low surrogate such as \uDC00, is not valid Unicode text. The older fallback behavior substitutes U+FFFD, whose UTF-8 bytes are EF BF BD. That keeps serialization moving, but it silently changes the VLV target and may seek to an unintended position.

Microsoft documents the strict encoding behavior in the .NET 10 LDAP compatibility note. I treat the resulting exception as input validation surfacing at the correct boundary, not as an LDAP server failure.

Build a deterministic multi-target probe

I use one project targeting both runtimes, with package versions pinned per target. That keeps the comparison explicit: System.DirectoryServices.Protocols 9.0.19 for net9.0, and the stable System.DirectoryServices.Protocols 10.0.11 package for net10.0.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>net9.0;net10.0</TargetFrameworks>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'net9.0'">
    <PackageReference Include="System.DirectoryServices.Protocols" Version="9.0.19" />
  </ItemGroup>
  <ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
    <PackageReference Include="System.DirectoryServices.Protocols" Version="10.0.11" />
  </ItemGroup>
</Project>

The probe covers four inputs: plain ASCII, a valid surrogate pair, an unpaired high surrogate, and an unpaired low surrogate. It calls GetValue() directly, so it exercises the control's BER serialization without opening an LDAP connection. For a successful encoding, it also checks the serialized bytes for EF BF BD.

using System.DirectoryServices.Protocols;
using System.Text;

var cases = new[]
{
    (Name: "ASCII", Target: "smith"),
    (Name: "Valid pair", Target: "\uD83D\uDE80"),
    (Name: "Unpaired high", Target: "\uD800"),
    (Name: "Unpaired low", Target: "\uDC00")
};

foreach (var item in cases)
{
    try
    {
        var control = new VlvRequestControl(0, 0, item.Target);
        var encoded = control.GetValue();
        var hasReplacement = Convert.ToHexString(encoded)
            .Contains("EFBFBD", StringComparison.Ordinal);

        Console.WriteLine(
            $"{item.Name}: encoded; replacement={hasReplacement}");
    }
    catch (EncoderFallbackException)
    {
        Console.WriteLine($"{item.Name}: EncoderFallbackException");
    }
}

The repository sample turns those observations into six assertions per target rather than relying on visual inspection. Its verifier runs both targets twice and also checks that repeated output is byte-for-byte identical:

dotnet restore .\LdapVlvValidation.csproj --nologo
dotnet build .\LdapVlvValidation.csproj --configuration Release --no-restore --nologo
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File ".\verify.ps1"

The verifier finishes with Summary: 5/5 passed. No directory, credentials, or runtime network access is required. The complete runnable sample is on main, and the focused change is recorded in the merged pull request.

Turn the result into a migration guardrail

The expected split is precise. Both targets accept ASCII and the valid surrogate pair without replacement bytes. The .NET 9 target accepts each unpaired surrogate and the serialized control contains EF BF BD. The .NET 10 target rejects each malformed value with EncoderFallbackException.

That makes this test useful during a .NET 9 to .NET 10 LDAP migration. If the modern target fails, the application has exposed malformed UTF-16 that used to be rewritten silently. I would trace the value back to its source and validate there, while retaining the boundary test so a future refactor cannot restore permissive behavior accidentally.

I would not "fix" the exception by replacing invalid code units myself. Replacement still changes the requested target. If the input comes from an API, queue, file, or user interface, rejecting it with a clear validation error preserves the distinction between invalid text and an LDAP connectivity problem.

Where I own the caller, I catch EncoderFallbackException at the validation boundary, translate it into a domain-level input error, and keep it out of generic retry logic. Retrying cannot repair malformed text, and treating the exception as transient can hide which record or request produced the value. I also avoid logging the malformed value itself; a safe source identifier and the validation category are enough to diagnose the path.

Limitations and when not to use this check

This sample verifies local control serialization only. It does not prove that a directory server supports virtual list view, that the server's sort rules match application expectations, or that paging and authorization are configured correctly. Those concerns need integration tests against the actual directory environment.

It also targets a narrow compatibility boundary. If an application never constructs VlvRequestControl, this specific regression test adds little value. A broader Unicode-validation policy may be a better investment for systems accepting text from many sources.

For applications that do use VLV targets, though, the offline test is fast, deterministic, and credential-free. It identifies the exact runtime change and keeps malformed input from being mistaken for a server-side LDAP issue.

What edge-case strings are you adding to your .NET 10 migration tests?

Happy testing!

OpenAI Usage API api_key_id: Reconcile Tokens and Costs by Key

Sukhpinder Singh — Mon, 31 Aug 2026 15:38:10 +0000

OpenAI Usage API api_key_id grouping solves a practical reporting gap: I can see which API key produced completion-token activity and which key accumulated cost. The tricky part is not making the two requests. It is joining their daily buckets without dropping unattributed or unmatched data.

I want a reconciliation report to expose gaps, not smooth them over. A missing cost row, a cost-only row, or a null key ID can each be useful evidence. This pattern keeps those cases visible with a deterministic .NET sample that needs no credentials or paid calls.

Why OpenAI Usage API `api_key_id` needs a full-outer join

OpenAI's August 4, 2026 API changelog added API-key filtering and grouping to the usage and cost APIs. That gives both responses a shared operational dimension, but it does not make them identical datasets.

The completions usage endpoint reports measures such as input tokens, output tokens, and model requests. Its api_key_id can be null. The costs endpoint returns monetary amounts and currency, also with a nullable API-key dimension.

An inner join would retain only rows present in both responses. That is attractive for a tidy chart, but unsafe for reconciliation. It can hide a key that has token usage but no matching cost row, a key with cost but no completion row, or an unattributed bucket.

I use a full-outer join keyed by (start_time, end_time, api_key_id) instead. Null or blank IDs become an explicit display value such as <unattributed>; they do not disappear.

Query both APIs at the same daily grain

The Costs API supports daily buckets, so I request bucket_width=1d from both endpoints. I also group by the same single dimension:

GET /v1/organization/usage/completions
    ?start_time=...
    &end_time=...
    &bucket_width=1d
    &group_by=api_key_id

GET /v1/organization/costs
    ?start_time=...
    &end_time=...
    &bucket_width=1d
    &group_by=api_key_id

Both resources paginate with has_more and next_page. I keep requesting pages until has_more is false. If a response says more data exists but omits its cursor, I fail the report rather than accepting a partial period. I also reject a repeated cursor to prevent a stuck pagination loop.

This alignment matters. Joining hourly usage against daily cost would manufacture mismatches. Adding model to only the usage grouping would make its row grain incompatible with the cost side. For this report, both sources must resolve to one row per UTC day and API-key ID.

Reconcile tokens and costs without inventing a price

After loading every page, the implementation creates separate indexes for usage and cost. It then unions their keys and assigns a status to every row:

var keys = usage.Keys
    .Concat(costs.Keys)
    .Distinct()
    .OrderBy(key => key.StartTime)
    .ThenBy(key => key.ApiKeyId, StringComparer.Ordinal);

var status = (hasUsage, hasCost) switch
{
    (true, true)  => ReconciliationStatus.Matched,
    (true, false) => ReconciliationStatus.UsageOnly,
    (false, true) => ReconciliationStatus.CostOnly
};

The indexes reject duplicate day/key pairs. That catches accidental extra grouping dimensions or repeated pages before they inflate totals. The cost index also uses decimal, retains the returned currency, and refuses to combine multiple currencies in one report.

The important boundary is that token counts and billed amount remain separate measures. I do not multiply tokens by a model price and compare that estimate with the Costs API. A cost bucket may contain line items beyond completion tokens, so equality would be an unsupported assumption.

The runnable sample on main uses two synthetic pages from each API. Its output contains four matched rows, one usage-only row, and one cost-only row. It also preserves a null key bucket as <unattributed>.

Nine offline checks verify pagination, the six-row full-outer result, status counts, null handling, separate token and cost measures, duplicate rejection, currency validation, and daily bucket alignment. The merged pull request records the exact restore, format, build, run, and dependency checks.

When this pattern is not enough

API-key grouping is useful for operational ownership, migration tracking, and coarse chargeback. It is not request-level attribution. If one key serves several products or customers, add your own request metadata and internal ledger at call time. Do not expect the organization usage report to reconstruct that boundary later.

A live collector also needs an organization Admin API key. Keep it in a secret manager or environment variable, never in source, logs, or fixtures. The sample avoids that risk by making no network requests; its identifiers and amounts are synthetic.

For a quick manual check, the dashboard may be enough. For repeatable reporting, I prefer the API plus explicit failure states: incomplete pagination, unmatched rows, unattributed activity, duplicate dimensions, and mixed currency should all be visible before anyone trusts a total.

Which gap would you alert on first: usage-only, cost-only, or unattributed?

Happy coding!

MCP C# Task Polling: Stop Infinite input_required Loops

Sukhpinder Singh — Mon, 31 Aug 2026 02:15:50 +0000

MCP Tasks let a tool finish asynchronously, but they also introduce a failure mode that a normal request timeout does not describe well: the task is alive, yet every poll returns the same input_required request. For MCP C# task polling, I want a bounded definition of “no progress,” not an endless loop or a user prompt that appears again and again.

The stable C# Tasks extension already provides that guard. The key is to set maxConsecutiveStuckPolls deliberately and test what happens when a server never advances.

Why MCP C# task polling can stall

In the MCP 2026-07-28 Tasks extension, a tool call can return a task instead of its final tool result. The client then uses tasks/get until the task completes, fails, is cancelled, or asks for input.

An input_required result contains keyed requests. A simplified response looks like this:

{
  "taskId": "task-1",
  "status": "input_required",
  "pollInterval": 1,
  "inputRequests": {
    "approval": {
      "method": "elicitation/create"
    }
  }
}

The key matters. If the next poll returns approval again, it is not a new question. Presenting it twice can produce duplicate confirmations or conflicting responses. Polling forever is not better; it hides a server that has stopped making useful progress.

The official C# SDK Tasks guide says CallToolWithPollingAsync deduplicates input-request keys. It also detects repeated input_required polls that contain no new keys, makes a best-effort tasks/cancel call, and throws McpException. The default stuck-poll threshold is 60.

Put a bound on MCP C# task polling

The extension method keeps the policy close to the call:

try
{
    CallToolResult result = await client.CallToolWithPollingAsync(
        new CallToolRequestParams { Name = "long-running-tool" },
        maxConsecutiveStuckPolls: 3,
        cancellationToken: cancellationToken);

    // Consume the completed tool result.
}
catch (McpException exception)
{
    logger.LogWarning(exception, "MCP task stopped making progress");
}

I use 3 in a fast verifier, not as a universal production value. The practical time bound is approximately the threshold multiplied by the server's poll interval. A task polled every second and a task polled every 30 seconds should not automatically share the same threshold.

This guard complements the caller's CancellationToken. Caller cancellation answers “does my operation still need this result?” The stuck-poll guard answers “is the server returning any new work or state?” Those are different decisions, and keeping both makes the failure easier to diagnose.

Reproduce the repeated input_required loop offline

My complete sample on main uses ModelContextProtocol.Extensions.Tasks 2.2.0 and an in-memory transport. It advertises MCP 2026-07-28, returns a task from tools/call, and then returns the same approval request key on every tasks/get call.

The elicitation handler declines the request and counts how often it runs:

Handlers = new McpClientHandlers
{
    ElicitationHandler = (request, cancellationToken) =>
    {
        elicitationCalls++;
        return ValueTask.FromResult(
            new ElicitResult { Action = "decline" });
    },
};

With a stuck limit of three, the observed contract is precise:

The handler runs once for the approval key.
The client sends one tasks/update containing approval: decline for task-1.
There are four tasks/get calls: one that introduces the key, then three with no new key.
The client sends one best-effort tasks/cancel for task-1.
The call throws McpException instead of polling again.

The verifier runs twice and compares the output byte for byte. It requires no MCP host, model account, credentials, clock, random values, or runtime network access. The merged pull request also records the exact restore, format, build, run, package, and vulnerability-audit commands.

The package used here is the stable ModelContextProtocol.Extensions.Tasks 2.2.0 release. Tasks are part of the final MCP 2026-07-28 extension model; the official release notes explain the poll-based lifecycle.

Choose the threshold—and know its limits

A low threshold is useful in a unit test because it turns a potential hang into a quick deterministic failure. In production, the same value could cancel a healthy task while a person is considering an approval prompt. I would choose it from the expected poll interval, normal response latency, and the cost of leaving remote work active.

Cancellation is cooperative and eventually consistent. A successful tasks/cancel response does not prove that remote work stopped at that exact instant, so callers must tolerate a late state transition and avoid assuming rollback.

This pattern is also not a replacement for an overall deadline, retry policy, or server-side task expiry. It specifically protects the polling loop when input_required repeats without a new key. Log task IDs and state transitions for diagnosis, but keep elicitation answers and credentials out of logs.

What stuck-poll threshold fits your server's poll interval and expected human response time?

Happy coding!

OpenAI Responses API `user` Migration: Split Safety from Prompt Caching

Sukhpinder Singh — Sun, 30 Aug 2026 16:15:42 +0000

The OpenAI Responses API user migration is easy to misread as a one-field rename. It is actually a split. The deprecated field mixed end-user safety attribution with prompt-cache routing, while the current request contract provides safety_identifier and prompt_cache_key for those separate jobs.

I would rather make that distinction explicit in one request builder than scatter it across call sites. The result is easier to review, keeps raw identity out of the payload, and can be verified without sending a model request.

Why OpenAI Responses API `user` migration is a split

The Responses API create reference marks user as deprecated and says it is being replaced by both fields. It describes safety_identifier as a stable end-user identifier used to help detect policy abuse, with a maximum length of 64 characters. It describes prompt_cache_key as a key that helps route requests with similar reusable prefixes.

Those are different lifecycles.

A safety identifier should remain stable for one account across prompts. In this scheme, I change the cache key when the reusable prompt contract changes, and I can share it across users whose requests have the same prefix. Blindly copying the old value into both fields misses the chance to separate the policies; it may still be valid when the old value is privacy-preserving and per-user cache grouping is intentional.

I model the split with two inputs:

a canonical internal subject for identity;
a cache group plus prompt-contract version for routing.

That makes a review question concrete: does this value identify a user, or does it identify reusable prompt structure?

Build two values from two policies

OpenAI's safety guidance recommends hashing a username or email instead of sending identifying information. In production I prefer an opaque internal account ID when one exists. I also use HMAC-SHA-256 with a secret pepper, rather than an unkeyed hash, so a copied digest is less useful for guessing common identifiers.

HMAC is an application choice here, not an API requirement. The pepper belongs in a secret manager and should be at least 32 random bytes. The committed sample uses an obvious fixed fixture solely to keep its output reproducible.

The derived value remains a stable, linkable pseudonym—not anonymous—and its privacy depends on protecting the pepper.

var subjectBytes = Encoding.UTF8.GetBytes(subject);
var safetyIdentifier = Convert.ToHexString(
    HMACSHA256.HashData(privacyPepper, subjectBytes))
    .ToLowerInvariant();

var promptCacheKey =
    $"{cacheGroup.Length}_{cacheGroup}_{cacheVersion.Length}_{cacheVersion}";

if (promptCacheKey.Length > 64)
    throw new ArgumentException("Prompt cache key is too long.");

var request = new
{
    model = "your-model",
    input,
    safety_identifier = safetyIdentifier,
    prompt_cache_key = promptCacheKey
};

The lowercase hexadecimal digest is exactly 64 characters, which fits the documented safety-identifier maximum. The sample also caps the cache key at 64 characters and restricts its components to a conservative ASCII subset. Length prefixes keep pairs such as a-b plus c distinct from a plus b-c.

The cache key says nothing about the person. In the sample, 12_support-flow_2_v3 identifies one reusable prompt contract; changing the prompt contract to v4 changes the key.

That separation also makes rotation decisions visible. Rotating the HMAC pepper changes safety identifiers, so a production rollout may need a deliberate overlap plan. In this sample's policy, a deliberate prompt-contract revision advances the cache version even when the identity policy stays unchanged.

Verify the payload before transport

The runnable sample on main uses only the .NET 10 shared framework. It builds JSON locally and performs fourteen checks, including these invariants:

user is absent
safety_identifier is stable for the same subject
different subjects produce different identifiers
raw identity is absent from JSON
prompt_cache_key is shared across matching prompt contracts
a prompt-version change produces a different cache key

It also rejects a short pepper before a transport boundary and serializes the same request twice to prove the bytes are identical. The executable makes no OpenAI request and requires no runtime network connection; restore and vulnerability-audit commands may contact configured NuGet sources.

This is useful because a successful HTTP response would not prove the migration is correct. Both replacement fields are optional. A request can be accepted while omitting the per-user safety signal, the application-supplied cache-routing key, or both. A local contract test catches the omission where the request is assembled.

The prompt-caching guide adds one important boundary: prompt_cache_key influences routing, but it does not pin traffic to a machine or guarantee a cache hit. Prefix content still has to match, and cache eligibility depends on the model and prompt shape. I treat the key as a routing hint, not a response cache or correctness mechanism.

Limits and when not to use this pattern

This sample does not prove that OpenAI accepts a chosen model, that a cache read occurs, or that any safety action will result. Those belong to integration tests and production telemetry. It also does not prescribe one universal cache-key scheme; high-volume applications should tune grouping against real prefix reuse and overflow behavior.

For anonymous previews, OpenAI's guidance allows a session ID as the safety identifier. For trusted internal batch jobs with no individual end user, forcing a fictional per-user identity would be misleading. I would document that boundary instead of inventing one.

The practical migration rule is small: remove user, derive safety_identifier from a stable privacy-preserving identity policy, derive prompt_cache_key from a reusable prompt policy, and test both independently.

What deprecated request field are you turning into an explicit contract test next?

Happy coding!

MCP C# Per-Request Client Capabilities: Read the Request, Not the Server

Sukhpinder Singh — Sat, 29 Aug 2026 15:07:15 +0000

With MCP C# per-request client capabilities, the 2026-07-28 protocol changes where a server must read what the caller supports. Modern stateless requests carry their own clientCapabilities inside _meta; there is no initialization handshake whose values can be retained for the connection.

That creates a small but important C# trap. Inside a stateless HTTP handler, request.Server.ClientCapabilities is intentionally null. The authoritative value lives on the current JSON-RPC request. If I cache a previous value, or treat the server property as the modern source, I can make the wrong decision for the next call.

Why MCP C# per-request client capabilities moved

The MCP 2026-07-28 release removed protocol-level sessions and the initialize exchange from the modern path. Every request is self-contained, which lets separate server instances handle calls without sticky routing or a shared MCP session store.

The request now carries reserved metadata such as:

{
  "_meta": {
    "io.modelcontextprotocol/protocolVersion": "2026-07-28",
    "io.modelcontextprotocol/clientInfo": {
      "name": "report-client",
      "version": "1.0.0"
    },
    "io.modelcontextprotocol/clientCapabilities": {
      "extensions": {
        "com.example/report-export": {}
      }
    }
  }
}

The key word is request. A server must not infer capabilities from an earlier message. Two calls reaching the same process may legitimately declare different extension support, and concurrent handlers must stay isolated.

The older handshake model encouraged a connection-level mental model: negotiate once, then consult the negotiated server object later. That assumption does not survive a sessionless request that can land on any instance. There is no durable "current client" whose feature set safely belongs in a singleton, static field, or process-wide cache. Even when one client normally sends the same declaration each time, the protocol boundary still has to treat the envelope it received as the source for that call.

This also matters during staged migrations. A load test, proxy, or compatibility client can mix modern requests with different extension maps in one server process. Code that appears correct with one client may fail only under overlap, which is why I prefer a concurrency regression instead of a single serialized example.

I used the stable ModelContextProtocol.AspNetCore 2.2.0 package for the sample. This is released functionality, not a preview API.

Read the request, not the stateless server

The C# SDK exposes the parsed value through JsonRpcMessageContext.ClientCapabilities. A tool can reach it from its injected RequestContext<CallToolRequestParams>:

public async Task<string> InspectClientCapabilityAsync(
    string requestName,
    RequestContext<CallToolRequestParams> request,
    CapabilityBarrier barrier,
    CancellationToken cancellationToken)
{
    await barrier.WaitForBothAsync(cancellationToken);

    var capabilities = request.JsonRpcRequest.Context?.ClientCapabilities;
    var enabled = capabilities?.Extensions?
        .ContainsKey("com.example/report-export") is true;

    var serverValue = request.Server.ClientCapabilities is null
        ? "null"
        : "set";

    return $"{requestName}:request={(enabled ? "enabled" : "disabled")},server={serverValue}";
}

The official JsonRpcMessageContext reference calls the current request authoritative. That is the contract I want the code to make visible.

Keeping the lookup beside the tool decision makes the null cases easier to reason about. A missing request context means I do not have an affirmative declaration. An empty extensions dictionary means the client sent a valid capability object without this extension. Neither should silently fall back to whatever the previous handler observed.

Notice that I am checking an extension declaration, not granting access. Client capabilities are self-reported protocol features. They are useful for deciding whether a response shape or interaction is supported, but they are not authentication, authorization, or trusted identity. A protected report export still needs validated claims and application policy.

Reproduce overlapping calls offline

A sequential happy-path test can miss cross-request state. The complete sample starts an ASP.NET Core TestServer, so it exercises the real Streamable HTTP endpoint without opening a port.

It sends two tools/call requests concurrently. One advertises com.example/report-export; the other sends an empty extensions map. A one-shot barrier pauses both tool handlers until they have arrived, then lets each read its request context. The verifier expects:

enabled-request:request=enabled,server=null
disabled-request:request=disabled,server=null

That assertion checks two boundaries at once: each call retains its own capability value, and the stateless server property is not mistaken for the request metadata source.

The barrier is deliberate. Both handlers arrive before either reads the capability, so the test does not pass merely because the requests happened to run one after another. If application code moved the declaration into shared mutable state, this arrangement would expose the last-writer-wins mistake. The five-second guard turns a broken dispatch path into a failure instead of leaving the test process blocked.

The verifier also sends a modern request that omits io.modelcontextprotocol/clientCapabilities. The SDK rejects it before the tool runs with HTTP 400 and JSON-RPC code -32602. That is different from a well-formed request that declares capabilities but lacks a feature a particular operation requires.

Run the checks with:

dotnet restore
dotnet format --verify-no-changes --no-restore
dotnet build --configuration Release --no-restore
dotnet run --configuration Release --no-build
dotnet list package --vulnerable --include-transitive

The pull request and validation record are available here. The sample uses fixed JSON, an in-memory server, and no MCP host, credential, model call, database, or runtime network request.

Limits and when not to use this gate

This pattern targets the modern stateless HTTP path. Initialize-era clients establish capabilities during the legacy handshake, so migration code that supports both eras should follow the SDK's version-specific behavior rather than manually copying _meta into a global cache.

The sample also checks one custom extension, not every built-in capability or extension schema. In production I would centralize the extension name and validate any settings object before consuming it. I would still pass the current request into that policy rather than storing a mutable capability snapshot. If several tools need the same decision, a request-scoped service is a better home than a singleton.

I also would not add a capability check to ordinary tools that never depend on an optional client feature. More gates create more failure modes. Read the metadata where a response or interaction genuinely requires it, keep the check request-scoped, and test the missing declaration separately from an unauthorized caller.

How are you testing request-scoped metadata before moving an MCP server to the 2026-07-28 path?

Cheers!

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!

DEV Community: Sukhpinder Singh

MCP Python SDK Extension Method Collisions: Fail Before the Server Starts

Why collisions should fail during startup

Build a version-pinned MethodBinding

Verify MCP Python SDK extension method collisions offline

Limitations and when not to use this pattern

.NET 10 Generic Math Shift Masking: Catch Overshifts That Now Wrap

Why .NET 10 generic math shift masking changes results

Reproduce the .NET 9 and .NET 10 boundary

Make the shift-count policy explicit

When not to use modulo masking

EF Core 10 Named Default Constraints: Preview the Migration SQL Before Deploying

Why EF Core 10 named default constraints can surprise CI

Preview the migration SQL without SQL Server

Turn the migration preview into a deterministic gate

When I would avoid the global convention

OpenAI Responses API previous_response_id Instructions: Repeat Policy on Every Turn

Why OpenAI Responses API previous_response_id instructions disappear

Make the continuation contract explicit

Verify the chained payload offline

Limits and when not to use this guard

.NET 10 InlineArray Explicit Size: Fix TypeLoadException with a Wrapper

Why the loader rejects the old shape

Reproduce the TypeLoadException safely

Fix .NET 10 InlineArray explicit Size with a wrapper

What I would gate during an upgrade

.NET 10 LDAP VlvRequestControl Validation: Stop Sending Replacement Bytes

Why .NET 10 LDAP VlvRequestControl validation matters

Build a deterministic multi-target probe

Turn the result into a migration guardrail

Limitations and when not to use this check

OpenAI Usage API api_key_id: Reconcile Tokens and Costs by Key

Why OpenAI Usage API api_key_id needs a full-outer join

Query both APIs at the same daily grain

Reconcile tokens and costs without inventing a price

When this pattern is not enough

MCP C# Task Polling: Stop Infinite input_required Loops

Why MCP C# task polling can stall

Put a bound on MCP C# task polling

Reproduce the repeated input_required loop offline

Choose the threshold—and know its limits

OpenAI Responses API `user` Migration: Split Safety from Prompt Caching

Why OpenAI Responses API user migration is a split

Build two values from two policies

Verify the payload before transport

Limits and when not to use this pattern

MCP C# Per-Request Client Capabilities: Read the Request, Not the Server

Why MCP C# per-request client capabilities moved

Read the request, not the stateless server

Reproduce overlapping calls offline

Limits and when not to use this gate

Claude API Workspace Verification: Catch Misrouted Requests Before Attribution

Why Claude API workspace verification belongs on the response

Compare intent with the resolved workspace

Make the workspace check deterministic

Limits and when not to enforce it

Claude Structured Outputs Refusal Handling: Stop Parsing HTTP 200 Refusals

The schema is only one part of the contract

Make Claude structured outputs refusal handling a decoder boundary

Prove the edge cases offline

Limitations and when not to use this pattern

Build a version-pinned `MethodBinding`

Why OpenAI Usage API `api_key_id` needs a full-outer join

Why OpenAI Responses API `user` migration is a split