Write-Path Response Filtering (@mcp_light) — Nautobot Integration Validation

Date: June 2026

FMCP Version: 0.9

Agent: Claude.ai (Web based)

Status: Validated Date: 2026-06-03 Target: frisian-mcp installed in Nautobot (DCIM module) Scope: Live validation of write-path response filtering against a production-grade DRF surface

Summary

frisian-mcp's metadata-first philosophy was extended from the read path (@mcp_heavy) to the write path (@mcp_light). Prior to this work, every create/update/delete — including bulk operations — echoed the full serialized object(s) back to the calling agent. For mutation-heavy sessions this re-introduced the exact context-exhaustion problem the read-path filtering already solved: large volumes of near-identical confirmation JSON consuming agent context for no informational gain.

@mcp_light changes the default write response to a lean confirmation envelope, with an explicit agent opt-in (verify=true) to return the full object when verification is actually wanted.

This report documents the two build states validated against a live Nautobot instance: the baseline build (full-echo writes) and the @mcp_light build (lean-by-default writes), with measured token/byte costs for each.

Test Method

All measurements were taken against a live Nautobot 3.1.2a0 instance (Django 5.2.13) with frisian-mcp serving the DCIM ViewSet surface via the dispatcher pattern. The test object was a dcim.device created in an existing location (the AMS data center), using a device type, role, and active status already present in the environment.

Byte counts are the serialized response payload size. Token estimates use the standard 4 bytes per token approximation. The single-device test object serialized to 1,856 bytes of full response; production devices with rack, IP, platform, and config-context populated are substantially larger (3,800 bytes/device), so real-world reductions exceed the figures measured here on minimal test objects.

Build 1 — Baseline (Full-Echo Writes)

In the baseline build, every write action returned the complete DRF-serialized object: the record's ID and name plus all nested reference objects (device_type, status, role, location, rack), hyperlinked URLs, natural slug, timestamps, custom fields, computed fields, relationships, and config context.

Behavior

Operation Response Payload
Single create Full serialized object ~1,856 bytes / ~464 tokens
Bulk create (N objects) N full serialized objects N × ~1,856 bytes

Token cost

A single create returned roughly 1,856 bytes (~464 tokens) for a minimal device. The cost scales linearly with batch size and with object richness:

Scenario Object size Full-echo payload Est. tokens
Single create (test object) 1,856 B 1,856 B ~464
60-device bulk (test object size) 1,856 B ~111,360 B ~27,840
60-device bulk (production size) ~3,800 B ~228,000 B ~57,000

The 60-device production-scale row corresponds to the originating incident: a bulk device creation that dumped tens of thousands of tokens of confirmation JSON into agent context for zero informational gain. There was no agent-side mechanism to suppress the echo.

Build 2 — @mcp_light (Lean-by-Default Writes)

In the @mcp_light build, write actions default to a lean confirmation envelope. The full serialized object is still produced server-side and cached under a continuation token, but it is not returned unless the agent opts in. The envelope carries everything needed to continue a multi-step workflow (id, url, name) plus a size signal (data_size) so the agent knows the cost of what it is skipping, and a continuation_token to retrieve the full object later without re-running the write.

Behavior

Operation Default response Opt-in (verify=true)
Single create {id, url, name, data_size, continuation_token} Full serialized object
Bulk create {accepted, failed, data_size, continuation_token} Full serialized objects

Measured responses

Single create (lean default):

{
  "id": "7f489577-a113-48d2-88f0-d26f71c140dd",
  "url": "<resource url>",
  "name": "ams01-spine-09",
  "data_size": 1856,
  "continuation_token": "<opaque>"
}

~110 bytes returned in place of 1,856 bytes of full object.

Single create with verify=true (opt-in full object):

Returns the complete serialized object directly — no envelope, no continuation token. The verify parameter is consumed by the MCP layer and stripped before dispatch, so the host serializer never sees it. This path behaves identically to the baseline build, by design, for the cases where an agent genuinely needs the full record back.

Bulk create (lean summary):

{
  "accepted": 3,
  "failed": 0,
  "data_size": 5565,
  "continuation_token": "<opaque>"
}

~85 bytes returned in place of three full objects (5,565 bytes). The summary shape is flat — it does not grow with batch size.

Token cost

Scenario Object size Lean payload Est. tokens
Single create 1,856 B ~110 B ~28
3-device bulk 5,565 B (total) ~85 B ~21
60-device bulk (test object size) ~111,360 B ~85 B ~21
60-device bulk (production size) ~228,000 B ~85 B ~21

The lean envelope is effectively constant regardless of batch size or object richness, because it reports a count and a size rather than the objects themselves.

Before / After Comparison

Operation Build 1 (full echo) Build 2 (@mcp_light lean) Reduction
Single create 1,856 B / ~464 tok ~110 B / ~28 tok ~94%
3-device bulk 5,565 B / ~1,391 tok ~85 B / ~21 tok ~98.5%
60-device bulk (test size) ~111,360 B / ~27,840 tok ~85 B / ~21 tok ~99.9%
60-device bulk (production size) ~228,000 B / ~57,000 tok ~85 B / ~21 tok >99.9%

Design Properties Validated

  • Lean by default. No agent action is required to get the compact response; the saving is the default behavior, not an opt-in.
  • Informed opt-in. data_size tells the agent exactly how many bytes it is skipping, so the decision to call verify=true is informed rather than blind.
  • No re-execution. The continuation_token retrieves the cached full object via the existing read-path fetch mechanism. The write is never run twice; there is no risk of duplicate creation.
  • Full-object opt-in works. verify=true returns the complete serialized object directly, with the protocol parameter stripped before it reaches the host serializer.
  • Bulk summary is flat. The bulk response reports accepted / failed counts plus a size signal, so a 3-device and a 60-device bulk return responses of essentially the same size.
  • Read paths unaffected. List and retrieve behavior is unchanged; the write-path filtering is isolated to mutation actions.

Notes for Integrators

  • Bulk create calling convention. Bulk creation is performed by passing an array of objects to the create action under the data argument. There is no separate bulk_create action; the create action detects the array. Passing the list under any other key is rejected with an invalid-arguments error.
  • data_size vs tokens. The envelope reports bytes, not tokens, to avoid a server-side tokenizer dependency. Agents can estimate tokens at roughly 4 bytes per token.
  • Production object size. Measurements here use a minimal device (1,856 B). Fully populated production devices are larger (3,800 B), so production reductions exceed the figures above.

Conclusion

@mcp_light extends frisian-mcp's metadata-first design to the mutation path without sacrificing the ability to retrieve full objects when needed. The lean envelope reduces single-write payloads by ~94% and bulk-write payloads by upwards of 99%, collapsing what was previously a linear, batch-size-dependent context cost into a flat, constant-size confirmation. The originating problem — bulk device creation flooding agent context with redundant confirmation JSON — is resolved, and validated live against a production-grade DRF surface.