This detail is called Context Budgeting.

The Root Problem: The Elegance of MCP and Its Hidden Cost

Model Context Protocol (MCP), as a relatively young standard, introduced a unified paradigm for integrating AI with application systems. The intent is sound—by defining clear JSON Schemas, it enables models to understand and use arbitrary tools. However, in high-concurrency, high-complexity enterprise environments, this “complete declaration” approach is revealing fundamental limitations.

Picture this scenario: You have 15 microservices, each exposing 7-8 API endpoints on average. Add integrations with GitHub, Azure DevOps, Atlassian, and other third-party platforms. The result: 100+ available “tools” in your system.

Each tool requires a detailed JSON Schema definition—parameters, types, validation rules, return value structures. MCP’s elegance lies in its completeness. But this completeness carries a hidden cost.

Cost One: The Economics of Tokens

Let’s do a simple calculation. A moderately complex API specification averages 150-300 tokens. For 100 tools, that’s 15,000-30,000 tokens in standing overhead. With models like Claude or GPT-4, where input token pricing is typically 1/3 of output pricing, this translates to:

• The “startup cost” of each request has already consumed a significant portion of the context window
• Within 200K or 100K context limits, the actual space available for problem-domain reasoning is severely eroded
• In production environments handling long conversations or complex multi-step reasoning, this cost rapidly becomes unacceptable

This is not merely an economic problem—it’s fundamentally an information density problem. The model’s attention mechanism experiences capability degradation when processing extremely long inputs. More tokens don’t mean better understanding; they risk burying critical information under mountains of Schema definitions.

Cost Two: Cognitive Load and Attention Fragmentation

From a neuroscience perspective, the Transformer architecture’s attention mechanism faces a fundamental trade-off when processing long sequences: signal-to-noise ratio.

MCP forces the model to browse all 100+ tool definitions with nearly identical probability weights before executing any operation. This means:

1. Information Competition: The model must distinguish “which tools truly matter for this task” from a sea of parameter definitions—a process that itself consumes cognitive resources.
2. Instruction Following Degradation: Research shows that when input length exceeds 60-70% of the context window, the model’s “Instruction Following” capability drops significantly.
3. Reasoning Trajectory Pollution: When generating reasoning steps, the model is easily distracted by irrelevant tool definitions, reducing reasoning path efficiency.

For enterprise applications requiring high reliability and consistency, this “cognitive pollution” is unacceptable.

The Quiet Renaissance of CLI

Against this backdrop, we’re witnessing an interesting counter-trend: mature AI Agent frameworks (like OpenClaw) increasingly turn toward CLI (Command Line Interface) rather than MCP when handling large-scale tool problems.

This may look like “technical regression.” But actually, it reflects a deeper insight: For any complex system, constraints themselves are features.

Core Advantage One: Zero-Entropy Intrinsic Knowledge Base

Consider this fact: Most modern LLMs have encountered millions of lines of Bash scripts, Git commands, Kubernetes YAML, and Azure CLI directives in their training sets. These tools form the “lingua franca” of internet infrastructure operations.

For these public CLIs (git, kubectl, az, gh, etc.), models possess prior knowledge. Moreover, these command-line tools follow consistent design patterns:

• The standard <command> <subcommand> --flag value structure
• Self-documenting capability through --help
• Immediate learning ability via man or --help

In other words, the model doesn’t need us to re-explain “what is git” in the prompt—it’s already a resident in the model’s knowledge base. We simply tell the Agent “use git commands to complete this task,” and the model can automatically reason about potential command combinations.

This “Pull Mode” rather than “Push Mode” tool discovery has qualitative advantages in token cost.

Core Advantage Two: Pipelines—The Breakthrough in Execution Density

Now let’s discuss why pipelines are CLI’s greatest advantage over MCP.

Consider a real workflow:

Scenario: Find error logs in a microservice, extract related request IDs, query the trace system for complete call chains of these IDs, then restart the affected service instances.

How would this unfold in MCP mode?

Agent: I need to view logs from microservice A
[Model calls Tool: GetLogs(service='A', filter='error')]
Result: Returns 100 log records with request IDs and timestamps

Agent: I need to extract request IDs from these logs
[Model calls Tool: ParseLogs(logs=[...], pattern='request_id')]
Result: Returns 20 unique request IDs

Agent: I need to query the trace system for these IDs' call chains
[Model calls Tool: QueryTraces(request_ids=[...])]
Result: Returns call chain data

Agent: Based on the call chains, I need to restart these services
[Model calls Tool: RestartServices(services=[...])]
Result: Services restarted

This requires 4 model roundtrips. Each roundtrip not only consumes tokens but introduces intermediate decision points. The model must confirm intent, evaluate results, and decide the next step at each stage. Any uncertainty or misunderstanding in this process can derail the trajectory.

In CLI mode:

ms logs --service A --filter error | \
  grep -oP 'request_id=\K[^,]*' | \
  sort -u | \
  xargs -I {} ms traces --request-id {} | \
  jq -r '.services[]' | \
  sort -u | \
  xargs -I {} ms restart --service {}

The Agent generates this command once. The system then executes deterministically through the pipeline. No intermediate decision points, no roundtrip delays or uncertainty.

This is the difference in Execution Density. CLI achieves “logic fusion” through pipelines, compressing steps scattered across multiple reasoning phases into a single execution instruction.

From a cost perspective:

• MCP approach: 4 roundtrips × ~500 tokens/roundtrip = 2000+ tokens consumed
• CLI approach: 1 generation + standard command execution = just the pipeline command’s token cost

This is no longer in the optimization realm—it’s a physics-level dimensional reduction—from 2000+ tokens of multiple roundtrips down to a single few-hundred-token pipeline instruction. This represents roughly a 10x difference. When we see 444x or even 800x differences in tool definition costs later, the magnitude of change becomes truly striking.

Beyond tokens, the deeper advantage is deterministic failure recovery. In MCP mode, any step’s failure requires the model to re-evaluate and adjust. In CLI mode, any command failure is natively captured by bash (via set -e or error handling), providing immediate feedback. This clear fault boundary makes reliable error handling easier to build.

Execution Density Comparison Diagram

Let’s visualize the fundamental difference between these two modes:

Enterprise Reality: The Challenge of Private Tools

So far, we’ve discussed advantages of “public CLIs.” But within enterprises, the situation is more complex.

Most enterprises maintain proprietary microservice orchestration toolsets. These tools aren’t in the model’s training set and can’t rely on “intrinsic knowledge.” If we simply switch to CLI without proper discovery and self-description mechanisms, the problem becomes: How can the Agent discover and understand these private commands?

If we don’t explicitly tell the LLM how each command works and what parameters it accepts, the model can’t judge how to call it correctly or which command to choose. But if we write detailed documentation for each command, that documentation’s volume and complexity often rivals what MCP’s Descriptions (JSON Schema) would require.

Merely replacing MCP with CLI without accompanying capability discovery and self-description mechanisms doesn’t fundamentally solve the integration challenge.

This is where design thinking needs to shift. My answer is: Router CLI architecture combined with dynamic self-description.

Solution: Unified Router CLI + Dynamic Self-Description

Suppose we design a unified command entry point:

ms <service-name> <action> [--option value]

This ms (Microservices) command acts as a central router with clear responsibilities:

1. Intent Routing: Determine the target microservice based on service-name
2. Action Dispatch: Call the specific microservice implementation based on action
3. Parameter Passthrough: Forward options and values to downstream services

Key Insight: From “Full Pre-Loading” to “On-Demand Hot Loading”

Let’s use a more engineering-focused framework for comparison—one the industry is adopting:

MCP’s “Eager Loading” Mode:

The moment the Agent starts working, all 100 tools’ complete JSON Schemas must enter Context. This resembles requiring someone to memorize every page of a 2000-page reference manual before taking an exam—regardless of whether the exam covers those sections. The result:

• Constant Context Consumption: 80,000 tokens occupied unconditionally, impossible to release
• Intensified Information Competition: The model’s every decision involves weighing among 100 complete definitions, fragmenting attention
• Cold Tool Pollution: Even if the session only uses 5 tools, the remaining 95 definitions’ mere presence constitutes reasoning interference

This is why MCP exhibits “token cost rigidity” in high-complexity systems.

Router CLI’s “Lazy Loading” Mode:

The system initially just says “I have an ms command.” Let’s trace a real enterprise session workflow:

【Step 0】Agent initialization
  Context contains only the `ms` entry point (~10 tokens)

【Step 1】User request: List all active users
  Agent executes: ms user --help
  → Context loads: user-service documentation (~50 tokens)
  → Agent reasoning: OK, I understand. Execute ms user list --filter "status=active"
  
【Step 2】Continued user operations
  Agent executes: ms user get --user-id 123
  → Note: No need to reload help; pattern is known

【Step 3】New requirement emerged: Initialize payment flow
  User request: Create a virtual card for the user
  Agent executes: ms payment --help
  → Context loads: payment-service documentation (~50 tokens)
  → Context pruning: Remove user-service help definition
     * In MCP: Would require client re-initialization at huge cost
     * In CLI: Implemented via system prompt (e.g., "Discard help for services not used in last 2 steps")
     * Framework auto-manages context lifecycle; developers don't intervene
  → Note: user-service patterns remain in Agent's execution memory; no reload needed

【Step 4】Execute payment operation
  Agent executes: ms payment card create --user-id 123 --card-type virtual
  → Success

【Session Summary】
  - Involved business domains: 2 (user + payment)
  - Actual context consumption: 10 + 50 + 50 = 110 tokens
  - MCP mode for equivalent session: Constant 80,000 tokens
  - Savings ratio: ~99.86%

This comparison illustrates the fundamental difference: In any real enterprise session, the Agent typically operates within 2-3 logical business domains. MCP forces permanent retention of all 100 domain definitions in Context. Router CLI lets Context dynamically adjust according to temporal/task flow, preserving only “hot” information.

Let’s visualize how this 99.86% savings is achieved:

This reveals a critical insight: MCP’s cost isn’t just constant—it’s cumulative. Each operation occurs within an 80,000-token quagmire. CLI maintains context at extremely low levels throughout the session, genuinely liberating reasoning space.

Second Layer: Leveraging “Form Semantics” to Reduce Description Burden

You might ask: Aren’t help text and JSON Schema essentially the same? Why does help save so many tokens?

The answer: Models possess innate heuristic understanding of CLI form.

When encountering ms user list --filter "status=active" --limit 100, the model doesn’t need detailed explanation:

• It knows list typically means “query a list”
• It understands --filter is a filter parameter
• It recognizes "status=active" follows Key=Value convention
• It infers --limit 100 restricts result count

These “form intuitions” derive from billions of lines of actual CLI code in training data.

By contrast, JSON Schema is purely machine language—the model depends 100% on explicit documentation:

{
  "parameters": {
    "filter": {
      "type": "string",
      "description": "Query filter expression following the pattern...",
      "pattern": "^(status|role|department)=(active|inactive|...)$",
      "examples": [...],
      "constraints": [...]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "default": 50
    }
  }
}

This creates a stark difference: CLI help can be radically concise:

ms user list
  Lists all users
  
  Options:
    --filter <query>   Query condition (status=active, role=admin, etc.)
    --limit <num>      Result count (default: 50)
    --sort <field>     Sort field (name, created_at, etc.)

While MCP requires 5-10x more tokens explaining type systems, constraints, and validation rules. The model’s POSIX command-line intrinsic knowledge becomes our “private knowledge library,” saving vast amounts of explicit documentation. This isn’t cutting corners—it’s leveraging model priors to optimize context utilization.

Third Layer: Defensive Allocation of Context Window

This raises a strategic consideration: every token is a scarce reasoning resource.

In MCP mode, context allocation is “passive”: 80,000 tokens are dead weight, leaving 120,000 for user problems, intermediate reasoning, and tool results. Models are forced to work in an extremely crowded environment, with attention inevitably scattered.

In Router CLI mode, we achieve active context defense:

• Hot tools (needed this session) occupy prominent context positions with highest attention weight
• Cold tools (possibly useful but unused) are lazy-loaded via --help, activated on demand
• Unrelated tools never enter Context, completely isolated

From an enterprise architecture FURPS+ perspective:

• Functionality: No regression; all tools remain accessible
• Usability: Improved; model isn’t drowned in massive definitions
• Reliability: Improved; bigger reasoning space means lower error rates
• Performance: Dramatic improvement; 100x+ token reduction
• Maintainability: Improved; new tools don’t impact existing sessions
• Scalability: Qualitative leap; from “context explodes at ~100 tools” to “handles 1000+ tools effortlessly”

Router CLI Design Best Practices

For this approach to work effectively, Router CLI must follow several design principles:

1. Minimize Interface Set

Group related operations under the same service. For instance, all user authentication operations belong under ms auth-service, not scattered across independent commands. Benefits include:

• Reduce top-level command count (100 → 20-30 services)
• Increase command “information density”—each top-level command represents a clear conceptual domain
• Help models build domain concepts—”authentication,” “payment,” “orders” as discrete business objects

2. Consistent Flags and Output Format

All commands follow identical flag naming conventions and output formats (e.g., JSON). After learning a few commands, the model can project these patterns to new commands.

3. Composability

Design commands for pipeline composability. For example, ms order list output should be structured JSON filterable by jq; ms order fetch --order-id <id> should return the same structure. Agents can naturally combine such commands.

4. Error Handling Clarity

Command failures should return non-zero exit codes and structured error messages, allowing bash to immediately capture errors without relying on model inference.

Practical Example: Token Cost Comparison

Let’s compare costs using our previous scenario. Assume 80 microservices, ~5 actions each, ~400 total operations.

MCP Mode: Complete JSON Schema for all 400 operations

• Average 200 tokens per Schema
• Total overhead: 80,000 tokens (constant overhead per request)
• Usable context with 200K limit: only 120K

CLI + Self-Description Mode: Unified entry + dynamic help

• Top-level ms --help: Lists 80 services, ~100 tokens
• First service invocation ms <service> --help: ~50 tokens
• Specific action ms <service> <action> --help: ~30 tokens
• Single request cost: 100 + 50 + 30 = 180 tokens (only on first interaction with a service)
• Subsequent same-service requests: just 100 tokens

Cost Differential — This transcends “optimization”:

• First complex operation: MCP’s 80,000 tokens vs CLI’s 180 tokens, ~444x difference
• Subsequent operations: MCP’s 80,000 tokens vs CLI’s 100 tokens, ~800x difference
• Real numbers: For a mid-size enterprise (100 daily requests), MCP consumes 8M tokens daily on tool definitions; CLI consumes just 18K tokens for dynamic help. This is collapsing from millions to tens of thousands.

This isn’t conceptual confusion—enterprise workloads are typically repetitive. Same queries, same operations execute repeatedly. CLI’s advantage is that token cost diminishes over time (as Agent understanding deepens), while MCP’s cost remains a constant monolith.

Context Utilization Comparison Diagram

Let’s visualize how both modes allocate the context window:

This reveals a fundamental truth: context window is inherently a scarce reasoning resource. MCP’s philosophy is “pre-reserve all possibilities”; Router CLI’s is “activate on-demand” and “optimize dynamically.”

Within a 200K context budget, MCP wastes 400x resources on cold tool definitions. Router CLI redirects these to “problem space”—where deep chain-of-thought reasoning, historical accumulation, and error recovery happen.

Deep Dive: Why This Difference Matters in Practice

1. Long-Chain Reasoning Capability

When diagnosing complex production issues, Agents might need to:

• Query logs (engaging multiple time-series)
• Extract information (preserving intermediate state)
• Cross-verify (building on results from earlier steps)
• Make decisions (requiring clear reasoning space)

In MCP mode, each step of this chain executes within a crowded 100-tool Context. Model attention constantly fragments, causing “Chain Forgetting”—later steps lose early constraints.

In Router CLI mode, the reasoning chain unfolds in a “clear” environment, with only current-session tools occupying attention.

2. Model Architecture-Level Performance Degradation

Research shows Transformer attention degrades significantly when input length exceeds 60-70% of context window (called “Context Limit Degradation”). In MCP, tool definitions alone occupy 40% of the window, compressing reasoning space to the efficiency inflection point. Router CLI by “timely release” of cold tools maintains reasoning space in the 80%+ sweet spot.

Security Considerations: Prompt Injection and Command Execution Risks

So far we’ve focused on efficiency advantages. But any technical decision involves tradeoffs. Router CLI introduces a risk requiring careful handling: command injection from prompt injection.

Risk Scenario

Consider:

User input: I want to query users named "admin'; DROP DATABASE;"
Agent-generated pipeline:
ms user list --filter "name=admin'; DROP DATABASE;"

While this specific example probably won’t directly execute SQL due to proper quoting, more complex scenarios could cause unintended command execution if bash parameter escaping is mishandled.

Defense Strategy

Production Router CLI systems require layered defense:

Layer One: Parameter Whitelisting and Type Validation

# In Router CLI implementation
ms user list --filter <STRING_WITH_STRICT_PATTERN>
# Rather than accepting arbitrary strings

Layer Two: Sandboxed Execution Environment Execute Agent-generated commands within containers or sandboxes, restricting accessible resources and command scope. This is an industry best practice reflecting “don’t trust model-generated code.”

Layer Three: Audit and Rollback Mechanisms Log all command executions and establish rapid rollback mechanisms. Misexecuted commands can be quickly recovered.

Layer Four: Agent-Side Defense Prompting Via prompt engineering, explicitly guide Agents to avoid special characters in parameters. Example:

When constructing CLI commands, ALWAYS escape user inputs using proper shell quoting.
For example, use 'admin'"'"'s users' instead of 'admin's users'.

Critically, these risks exist in MCP too—they’re not CLI-specific. Any tool-calling system needs such defenses. Router CLI doesn’t reduce security; it demands clearer understanding of “tool-calling trust boundaries.”

Public CLI: Out-of-the-Box Advantages

Another crucial mindset shift in enterprise systems: leverage existing public CLI tools aggressively; minimize custom tools.

Most major services provide comprehensive CLIs:

• AWS CLI / Azure CLI: Cover 90%+ of cloud operations
• kubectl: The standard Kubernetes interface
• gh (GitHub CLI) + curl + jq: Almost any API is accessible
• Atlassian CLI (or direct curl): JIRA, Confluence, etc.
• git: Version control and base operations

These tools’ massive advantage: models already know them. In prompts, just saying “use AWS CLI” lets models automatically reason about aws describe-instances, aws ec2 ... commands. No schema needed.

The recommended strategy in practice:

1. Prioritize public CLIs: During architecture design, ask “can I use existing CLI tools?”
2. Enhance via pipelines and scripts: Combine multiple public CLI tools into higher-level operations
3. Design CLI only for core private logic: Create custom CLI commands only for truly proprietary operations

The result: custom CLI count drops significantly. Perhaps what once required 30 custom tools now needs just 10. This directly translates to linear token cost and cognitive load reduction.

Architecture Decision Framework: When to Use MCP, When to Use CLI

Based on the analysis, here’s a practical decision framework:

This framework’s principle: prioritize token efficiency and cognitive load to select the right integration mode.

Conclusion: The Paradigm Shift

AI Agents have evolved from simple chatbots to enterprise automation programs. This shift demands more than better LLMs—it requires deep understanding of complex systems.

The MCP-to-CLI transition fundamentally reflects maturity:

1. CLI is more efficient abstraction. It replaces verbose Schema definitions with symbolic interfaces. Models process known symbol systems far more efficiently than understanding new data structures from scratch.

2. Pipelines represent paradigm shift. From single Tool Calls to multi-step Pipeline chaining, we gain not just token savings but execution determinism and system reliability—critical for production applications.

3. Router CLI enables scalability. For enterprise microservice arrays, Router CLI with dynamic self-description offers a scalable “tool discovery” path. Agents learn during execution without pre-declaring all possibilities.

4. Leverage existing tools. Fully leverage models’ intrinsic knowledge of public CLI tools; minimize custom tool count. This may be the fastest path to improved token efficiency.

Behind this shift lies deeper understanding of information theory and system design: when facing complex systems, constraints (like strict command formats) aren’t burdens—they’re features. They reduce model search space, elevate reasoning determinism, ultimately improving system efficiency.

This evolution moves from “more information enables better reasoning” to “carefully structured information enables optimal reasoning.” Just as mature architects choose well-designed APIs over vast documentation, future AI Agent systems will find true efficiency within clear CLI interfaces and orderly pipeline modes.

Extended Reading and Practical Recommendations

If you’re designing a new AI Agent system or improving an existing one, consider:

1. Token Audit: Calculate current tool definition tokens and compare actual usage frequency. You’ll likely find many “cold tools” rarely used.

2. Minimal Router CLI Prototype: Select 3-5 most-used services from your system. Design a Router CLI. Compare pre/post efficiency and token consumption.

3. Cognitive Load Metrics: Track agent “correction rate”—how often models misunderstand and make incorrect decisions. You’ll see significant improvement post-CLI migration.

4. Leverage Public CLI Knowledge: Explicitly list available public tools in your prompts. Let models self-select, rather than passively awaiting MCP declarations.

Enterprise AI Agent system efficiency ultimately depends on whether we organize tools and information in models’ most natural, efficient manner. CLI and Router architecture prove: sometimes, computing’s most ancient paradigm (command line) offers the deepest alignment with cutting-edge AI technology.

1. It Starts with an Innocent-Looking Request

Imagine you’re building a multi-step online form. Each time the user clicks “Next”, the frontend only needs to send the fields filled in on that step — not the entire form all over again.

That’s a perfectly reasonable requirement. To solve it, we chose JSON Patch (RFC 6902, official spec) — a standard format specifically designed to describe partial modifications to a JSON document.

A typical JSON Patch request looks like this:

[
  { "op": "replace", "path": "/firstName", "value": "Alice" },
  { "op": "replace", "path": "/dateOfBirth", "value": "1990-01-15" }
]

Straightforward enough: two replace operations, updating /firstName to "Alice" and /dateOfBirth to "1990-01-15".

So far, so good.

2. The Problem

Now look at the server-side data model. In a multi-step application, the backend maintains a single “state object” that spans the entire session. It contains two kinds of fields:

State Object
├── Fields the user fills in (client may modify)
│   ├── firstName
│   ├── dateOfBirth
│   ├── occupation
│   └── ...
│
└── Fields managed by the server (client must NEVER modify)
    ├── pricingToken        ← token generated by the pricing engine
    ├── policyNumber        ← assigned policy number
    ├── externalReferenceId ← correlation ID from an external system
    ├── redirectionUrl      ← server-injected redirect target
    ├── completedStages     ← stages the user has completed (used by flow guards)
    └── ...

The problem: the path in a JSON Patch request can point to any field.

A malicious user — or a security researcher — can craft a request like this:

[
  { "op": "replace", "path": "/pricingToken", "value": "my-forged-token" },
  { "op": "replace", "path": "/redirectionUrl", "value": "https://evil.example.com" },
  { "op": "replace", "path": "/completedStages", "value": ["step3", "step4"] }
]

Without any server-side defence, these operations are executed as-is:

• The pricing token is tampered with — subsequent underwriting calculations are based on forged data
• The redirect URL is overwritten — every dynamically generated link on the page now points to a malicious site
• Completed stages are fabricated — the user can skip flow validation and jump straight to checkout

This is an Overposting attack, also known as Mass Assignment — a classic vulnerability listed in the OWASP API Security Top 10 (OWASP API3: Broken Object Property Level Authorization).

3. Why JSON Patch Makes This Harder to See Coming

Mass Assignment exists in traditional REST APIs too, but there’s usually a natural layer of protection: developers define a dedicated DTO (request model) that only exposes the fields a client is allowed to set. The server then maps from the DTO to the domain object.

In a JSON Patch workflow, that protection simply doesn’t exist:

graph LR
    A[Traditional PUT/POST] --> B[DTO filter layer<br/>only exposes allowed fields]
    B --> C[Domain model]

    D[JSON Patch PATCH] --> E[No filter layer<br/>path can point to any field]
    E --> F[Domain model]

JSON Patch was designed to let you say precisely what you want to change — but that expressiveness is exactly what widens the attack surface. The target is no longer a constrained DTO; it’s the entire state tree.

The framework’s default JSON Patch handler (such as ASP.NET Core’s JsonPatchDocument) has no opinion on whether a given field should be writable by a client. It simply executes whatever path it’s given.

4. The Obvious Fix — and Why It Falls Short

The first instinct is to check each path before processing and reject anything on a blocklist:

// Blocklist approach
foreach (var operation in patchOperations)
{
    if (Blocklist.Contains(operation.Path))
        return BadRequest();
}

The problem: a blocklist requires manual maintenance and is inherently reactive.

Every time a new server-managed field is added to the model, someone has to remember to update the blocklist. That’s easy to forget — especially in a fast-moving codebase with multiple contributors.

More fundamentally, this violates the principle that security should be structural, not memorial.

5. The Right Approach: Let Fields Declare Their Own Access Level

A better model is to move the ownership of the protection rule to the field itself — declare at definition time whether a field can be modified by the client, rather than maintaining a separate list somewhere else.

This is the core mechanism we introduced: the [ClientReadOnly] annotation.

In the model, every server-managed field gets the annotation:

public class ApplicationStateModel
{
    // User-provided fields — no annotation, client may modify
    public string FirstName { get; set; }
    public DateTime DateOfBirth { get; set; }

    // Server-managed fields — annotated, client must not modify
    [ClientReadOnly]
    public string PricingToken { get; set; }

    [ClientReadOnly]
    public string PolicyNumber { get; set; }

    [ClientReadOnly]
    public List<string> CompletedStages { get; set; }
}

The benefit: the protection rule lives next to the field definition. When a developer adds a new field, they’re naturally prompted to decide: “Should this be [ClientReadOnly]?” The question is asked at the right moment — during design, not during a post-incident review.

6. Implementation: Intercept at the Model Binding Stage

The annotation alone doesn’t do anything. You need a mechanism to automatically strip out any Patch operations targeting annotated fields before they reach business logic.

We do this filtering at the Model Binding stage — the earliest point in the web framework’s request pipeline, before the request body is even deserialised into an object:

sequenceDiagram
    participant Client
    participant Custom ModelBinder
    participant Business Logic

    Client->>Custom ModelBinder: JSON Patch request (any operations)
    Note over Custom ModelBinder: Filter stage:<br/>Scan each operation's path<br/>Resolve the corresponding field<br/>If [ClientReadOnly] — silently discard
    Custom ModelBinder->>Business Logic: Sanitised operation list (only legitimate ops)
    Business Logic->>Client: Normal response

The core filtering algorithm:

private IList<Operation> FilterClientReadOnlyOperations(
    IList<Operation> operations, Type modelType)
{
    var result = new List<Operation>();

    foreach (var operation in operations)
    {
        // JSON Patch path format: "/fieldName" or "/nested/fieldName"
        var propertyPath = ParsePath(operation.Path);

        // Use reflection to resolve the field at the end of the path
        var property = ResolveProperty(modelType, propertyPath);

        if (property == null)
        {
            // Path points to a non-existent field — discard
            continue;
        }

        if (property.GetCustomAttribute<ClientReadOnlyAttribute>() != null)
        {
            // Annotation hit — silently discard, write to log
            _logger.LogWarning("Blocked ClientReadOnly field: {Path}", operation.Path);
            continue;
        }

        result.Add(operation);
    }

    return result;
}

Two implementation details worth calling out:

1. Path resolution must support nesting

A JSON Patch path can be deeply nested — for example, /profile/address. The algorithm needs to walk the path segment by segment (profile → address) until it reaches the terminal field, then check for the [ClientReadOnly] annotation.

2. Silently discard, don’t error

The filter drops illegal operations silently rather than returning a 400. The reasoning: an attacker should receive no useful feedback (denying reconnaissance). If the operation came from a framework bug or misconfigured tool, discarding is more resilient than breaking the request — and the log entry ensures the issue is still surfaced.

7. Plugging Into the Framework

In ASP.NET Core, Model Binding behaviour is extended via IModelBinderProvider. We implemented a custom FlowModelBinderProvider that performs the filtering above before any request reaches an action method, and registered it in the DI container to replace the default binder.

Every JSON Patch endpoint gets this protection automatically — no per-controller or per-action boilerplate required.

The full flow:

graph TD
    A[HTTP Request\nJSON Patch Body] --> B[FlowModelBinderProvider\nCustom Model Binder]
    B --> C{Scan each operation}
    C --> D[Resolve field via reflection\nalong the path]
    D --> E{Annotated with\nClientReadOnly?}
    E -->|Yes| F[Silently discard\nWrite to log]
    E -->|No| G[Keep operation]
    F --> H[Next operation]
    G --> H
    H --> I[Sanitised operation list]
    I --> J[Business logic layer\nController → Task → Service]

8. A Second Defence Layer: XSS Content Scanning

While building the Overposting defence, we added XSS content scanning in the same pipeline at no extra cost: each operation’s value is checked for dangerous patterns — <script> tags, inline event handlers (onXxx=), javascript: URIs, and similar. If any match, the entire request is rejected before it touches the application.

Together, the two layers form a combined defence:

9. Proving It Works: The Tests

Any security mechanism without test coverage is a security mechanism you can’t trust.

We wrote two test suites for the filtering logic:

ModelBinderHelperRemoveOperationsTests (validates filtering behaviour):

• A replace operation targeting a [ClientReadOnly] field → filtered out
• A replace operation targeting a non-annotated field → passes through
• A nested path (e.g. /profile/address) → correctly resolved and filtered
• A path pointing to a non-existent field → filtered out
• An empty operation list → returns empty normally

ModelBinderHelperBindValueTests (validates binding behaviour):

• Legitimate operations after filtering are correctly bound to model fields
• After filtering, the server-side value of a protected field remains unchanged

Together, these two suites cover both directions: “filtered what should be filtered” and “kept what should be kept.”

10. Three Principles of Security Design

This implementation prompted us to think more carefully about what good security design actually looks like.

1. Allowlist over blocklist; declaration over inspection

A blocklist asks developers to remember “this field is dangerous, so add it.” The [ClientReadOnly] annotation asks developers to consider “can the client modify this field?” The former is reactive; the latter is built into the design. Their failure modes are different: blocklists fail by omission, annotations fail by mislabelling — and deliberate omissions are far less common than forgotten list entries.

2. Enforce protection as early in the pipeline as possible

The filtering happens at the Model Binding stage. By the time business logic runs, the illegal operations don’t exist — they were removed at the gate. This mirrors how firewalls work: defence closest to the entry point is hardest to bypass.

3. Security mechanisms must have tests

Security code that passes today can silently break during a future refactor. Tests don’t just validate “it works now” — they’re a regression guard that protects the defence from being accidentally removed later.

Our system is an online insurance quoting platform. A user opens a web page, answers a series of questions — vehicle details, driving history, personal information — and the system calculates a premium in the background, presenting a final price for the user to accept or decline.

The flow spans more than a dozen steps. At each step forward, the backend sends the newly collected data to a downstream underwriting engine, retrieves the latest quote result, and displays it to the user.

The core interaction model is simple: user fills in → backend calculates → frontend shows result → user continues.

2. How SignalR Got In

At project kick-off, the team faced a design question: the underwriting engine’s calculation is asynchronous — it can’t return a result immediately. How do you push the result back to the frontend?

At the time, the underwriting engine and our application were part of the same deployment unit, and the team had full control over it. The technology choice was SignalR — Microsoft’s standard solution for real-time bidirectional communication in the .NET ecosystem, built on WebSockets with fallback support for Server-Sent Events and Long Polling.

On the architecture diagram, the solution looked elegant:

sequenceDiagram
    participant Browser
    participant BFF
    participant Underwriting Engine

    Browser->>BFF: Submit form data
    BFF->>Underwriting Engine: Initiate calculation
    BFF-->>Browser: 202 Accepted (return immediately)
    Underwriting Engine-->>BFF: Calculation complete
    BFF->>Browser: Push result via WebSocket Hub ✅

The user doesn’t have to wait — the backend pushes at the exact moment the calculation finishes, with minimal latency.

Was this the right choice? In certain scenarios, absolutely.

Over time, however, the underwriting engine was split out into an independent microservice, maintained by a separate team. Our application became a pure consumer — able only to call the interfaces it exposed, with no ability to modify its behaviour. What had once been an “internal implementation detail” was now a coupling point spanning a service boundary. By the time we started re-examining this design, the architectural reality had changed completely from when the original decision was made.

3. What SignalR Is Actually Good For

Before diving into our problems, let’s establish a baseline: SignalR is a solid technology. It solves a real class of problems.

The scenarios where SignalR genuinely shines share these characteristics:

graph LR
    A[Server-initiated events] --> B[Unpredictable timing]
    B --> C[Multiple clients need to receive simultaneously]
    C --> D[Clients cannot or should not poll]

Canonical examples:

• Collaborative documents (like Google Docs): any user’s edit must be synchronised in real time to everyone else with the document open
• Stock price dashboards: prices change every second; push is far more efficient than polling
• Chat rooms: message arrival is completely unpredictable; frequent polling wastes resources
• High-concurrency notification systems: tens of thousands of connections simultaneously waiting for server-side pushes

What these scenarios have in common: the server needs to broadcast to multiple connections, or the timing of events is truly unpredictable — the wait could be seconds or hours.

4. Looking Back at Our Actual Situation

Now apply that standard to our scenario.

How slow is our underwriting calculation?

From monitoring data: the vast majority of calculations complete in 1–2 seconds, with the slowest cases under 5 seconds. This isn’t “unpredictable, potentially long-duration waiting” — it’s a known, bounded window.

How many concurrent users are waiting?

Our platform sees tens of thousands to low hundreds of thousands of visits per day — a normal scale for a consumer insurance business. Even at peak, the number of users concurrently waiting for a quote calculation is quite limited. Insurance quoting is a deliberate, step-by-step process, not a flash sale.

Does the result need to be broadcast to multiple clients?

Not at all. Each calculation result belongs only to the one user who initiated that request. There is zero broadcast requirement.

A direct comparison:

Conclusion: Our scenario simply does not need SignalR. We brought a sledgehammer to drive a thumbtack.

5. The Real Cost of Maintaining SignalR

An ill-fitting architecture is a design problem, but at the engineering level it gradually becomes a maintenance burden.

Frontend complexity

To integrate with the SignalR Hub, the frontend had to maintain an entire infrastructure:

graph TD
    A[SignalR Module] --> B[Connection management<br/>establish / disconnect / reconnect]
    A --> C[HTTP Interceptor<br/>intercept requests, suspend until Hub callback]
    A --> D[Response Handler Service<br/>process messages pushed from Hub]
    A --> E[Awaitable Command model<br/>convert SignalR callbacks to Promises]
    A --> F[Test helper components<br/>Mock Hub / Mock Handler]

More than 10 files, each requiring development, testing, and maintenance. Every framework upgrade needed verification that this mechanism still worked. Every new engineer needed an explanation of “why does sending an HTTP request require waiting for a WebSocket callback before execution continues?”

Backend dependencies

The backend needed:

• A dedicated Azure SignalR Service (a managed service with its own cost)
• Hub class and connection management logic
• A full set of configuration options and validators

Test friction

Unit tests required mocking Hub behaviour; integration tests had to ensure WebSocket connections were stable in the test environment. These extra test infrastructure pieces created friction on every iteration.

6. The Alternatives We Evaluated

Before deciding to remove SignalR, we assessed several alternatives — worth going through one by one to explain why we didn’t choose them.

Option A: BFF-internal synchronous wait (making HTTP “look synchronous”)

The BFF receives the frontend request, polls the downstream calculation service internally, and only returns to the frontend once it has the result. From the frontend’s perspective, there is a single request/response.

sequenceDiagram
    participant Frontend
    participant BFF
    participant Underwriting Engine

    Frontend->>BFF: POST calculation request
    BFF->>Underwriting Engine: Initiate calculation
    Underwriting Engine-->>BFF: 202 Accepted
    loop BFF internal polling
        BFF->>Underwriting Engine: GET status
        Underwriting Engine-->>BFF: Not ready
    end
    Underwriting Engine-->>BFF: Calculation complete
    BFF-->>Frontend: 200 + result

Why we didn’t choose it:

• BFF HTTP connections have timeout limits (typically 30–60 seconds); if a calculation occasionally exceeds this, the frontend receives a 504 rather than a normal result
• BFF threads are blocked during the wait, increasing thread pool pressure under load
• Most importantly: the underwriting engine was by now an independent microservice — it only exposed a GET query interface, with no way for us to make it support “synchronous wait” semantics — we simply couldn’t change how it responded

Option B: Server-Sent Events (SSE)

SSE is HTTP’s one-way “streaming” mechanism: the server can continuously push data to the frontend, which receives via the EventSource API. Lighter than SignalR, no WebSocket required.

Why we didn’t choose it:

• Still requires a persistent connection; maintenance cost compared to SignalR is reduced but not eliminated
• Given that our known wait time is only 1–5 seconds, the overhead of keeping a connection open is not worth it
• Interaction with the downstream service still boils down to HTTP + polling; the only benefit of SSE would be in the frontend layer

Option C: Polling (what we ultimately chose)

The frontend issues an operation request. The BFF internally sends status queries to the downstream service until it confirms completion, then returns the final result to the frontend.

This is precisely the pattern that SignalR was originally designed to “replace.” In our scenario, it turned out to be the most appropriate choice.

7. Our Final Solution: BFF-Internal Polling

The architectural change looks like this:

sequenceDiagram
    participant Frontend
    participant BFF
    participant Downstream Service

    Note over Frontend,Downstream Service: Original approach (SignalR)
    Frontend->>BFF: POST/PATCH operation request
    BFF->>Downstream Service: Issue operation
    BFF-->>Frontend: 202 (return immediately)
    Downstream Service-->>BFF: Operation complete notification (WebSocket)
    BFF->>Frontend: Push result via SignalR Hub

    Note over Frontend,Downstream Service: New approach (BFF-internal polling)
    Frontend->>BFF: POST/PATCH operation request
    BFF->>Downstream Service: Issue operation
    Downstream Service-->>BFF: 202 (accepted)
    loop BFF internal polling
        BFF->>Downstream Service: GET query result
        Downstream Service-->>BFF: Result ready
    end
    BFF-->>Frontend: 200 + final result

From the user’s perspective, the experience is identical: click “Continue,” a spinner appears, and 1–2 seconds later the next step loads.

Polling strategy design

Polling is not an infinite loop. We use a linear incremental backoff strategy:

Poll 1: wait 1 second
Poll 2: wait 2 seconds
Poll 3: wait 3 seconds
...
Poll 7: wait 7 seconds
Maximum total wait: 28 seconds (1+2+3+4+5+6+7)

Why does the second poll usually give us the result?

This is the most critical engineering detail in the article: the downstream service caches GET responses, and every data mutation invalidates and immediately updates the cache. From the time a mutation request (POST/PATCH) is sent to when the cache is updated typically takes less than 1 second. So:

• Poll 1 (after a 1-second delay): hits the already-updated cache — almost always returns the result
• Only in rare cases (when the downstream service is under higher load) are polls 2 or 3 needed

In practice, 99% of cases complete within the first two polls, and the wait time perceived by users is indistinguishable from the original SignalR solution.

Where does polling apply?

Our polling is used for two categories of operation:

1. Create/delete operations: after issuing a POST or DELETE, confirm via GET that the resource has been created or deleted (GET returning 200 confirms creation; returning 404 confirms deletion)
2. Update operations: after issuing a PATCH, read the field values back via GET and compare against the expected values rather than relying solely on the status code

8. Pitfalls of Polling — and How We Handled Them

Polling looks simple, but there are a few details worth taking seriously in a production environment.

Pitfall 1: What happens when we time out?

28 seconds is already a long maximum wait. If we’ve polled 7 times and still haven’t received the expected result, something is seriously wrong with the downstream service.

Our approach: once the maximum retry count is exceeded, throw an exception, log detailed error information (including the actual state returned by the last GET), and return a 500 to the frontend, directing the user to contact support.

This is far better than leaving the user staring at a spinner indefinitely.

Pitfall 2: Test suites become unbearably slow

If 28 seconds of total wait time ends up inside a unit test, each test case takes tens of seconds, and the entire test suite becomes unusable.

Our approach: design the polling delay as an injectable property (set to 1 millisecond in the test environment). Unit tests complete in milliseconds; production behaviour and test behaviour are perfectly consistent.

Production: DelayMillisecondsPerRetry = 1000 (each wait = N × 1 second)
Test:       DelayMillisecondsPerRetry = 1     (each wait = N × 1 millisecond)

A small design detail, but one that saves a significant amount of test time in practice.

Pitfall 3: BFF threads blocked during polling

The BFF’s internal polling is implemented with async/await. During the wait, the thread is released back to the thread pool (Task.Delay is non-blocking), so there is no thread starvation. This is standard usage of the modern .NET async model — no special handling required.

Pitfall 4: Don’t confuse Polly retries with business-level polling

Our HTTP client is configured with both a Polly retry policy (for transient failures such as network errors and 5xx responses) and business-level polling (for waiting on downstream data synchronisation). The two are easy to conflate, and it’s important to keep them clearly separated:

In plain terms: Polly handles “the request failed — retry it”; business polling handles “the request succeeded, but the data hasn’t updated yet — check again.” These are two completely different problems.

9. The Result

A single PR to remove SignalR (a6e569dd):

• 77 files changed
• Over 1,200 lines of code deleted
• Net reduction of 548 lines
• 253 lines of new unit tests added in the same PR

From that point on, “the frontend issues an operation and waits for the result” no longer requires a WebSocket connection, a Hub class, an Interceptor, a ResponseHandler, or an AwaitableCommand. It’s a plain HTTP request, plus a polling loop quietly doing its job inside the BFF.

10. Closing Thoughts: Elegant Architecture Doesn’t Always Mean the Right Fit

SignalR isn’t wrong. It’s excellent technology with scenarios where it genuinely shines.

The real lesson here is: when choosing a technical solution, fit matters more than sophistication. Over-investing at the architecture level often isn’t a sign of poor engineers — it’s a sign that the intuition of “this technology looks correct” has obscured the question of “is this technology actually necessary for us?”

A few questions worth asking yourself at the next technology selection:

1. Is our data update truly “unpredictable” — or just “a little slow”?
2. Does this result need to be pushed to “multiple receivers,” or only to the one person who made the request?
3. If we used the simplest possible polling implementation, what’s the worst-case wait time for the user? Is that acceptable?
4. What is the maintenance cost for the team three months after introducing this technology?

Sometimes, one fewer dependency is the best architecture you can have.