When an Agent Cancels an MCP Tool Call Midway: Cleaning Up the Upstream Request
Quick answer A tool call that an agent cancels is not the same as a request that never happened. By the time the MCP client sends a cancellation, the server
Read articleThe Powerduck Blog
API engineering, from the spec out
Product updates, engineering notes, and guides for designing, debugging, testing, mocking, and serving MCP tools from one OpenAPI spec.
Browse the guidesThe Test Asserted the Entire Response and Broke When the API Added One Field
Quick answer An assertion that compares an entire API response to a fixed literal is testing for exact equality, and it is brittle by design. When the server adds a
Read articleMocking File Uploads: Returning 413 for an Oversized Payload and 201 on Success
Quick answer When you mock a file upload endpoint, do not return a single canned success for every request. The real server branches on the payload: a small upload returns
Read articleThe 412 Precondition Failed: A Stale If-Match Header Rejected Your Update
Quick answer A 412 Precondition Failed is not a generic server error. It means the client sent a conditional header such as If-Match or If-Unmodified-Since, and the resource no longer
Read articleThe Agent Removed a 'Dead' Export That Was Still Imported Through a Path Alias
Quick answer Do not let an agent delete an "unused" export just because a static analysis pass stopped referencing it. Modern codebases resolve imports through path aliases, barrel
Read articleWireMock's verify() Assertions vs Independent Spec-Based Checks
Quick answer WireMock's verify() confirms that a request matching a pattern actually reached the mock, and it is the natural way to assert your code called the right
Read articleRunning the Mock in Docker Compose for CI vs a Local Spec Server
Quick answer Running a mock inside Docker Compose gives every developer and the CI pipeline the same mock on a predictable address, with no local install or version drift. A
Read articleThe Embedded Try-It Console: CORS and Tokens in a Portal vs Static
Quick answer An embedded try-it console looks like a simple convenience, but it makes real cross-origin requests and has to handle CORS, credential storage, and token attachment. When the API
Read articleDocs Analytics: What a Hosted Platform Tracks vs Privacy-First Metrics
Quick answer Hosted documentation platforms collect a lot of telemetry by default, and much of it is aimed at the vendor's product analytics rather than decisions you actually
Read articleClient Certificates and mTLS in a GUI Client vs a Spec-Driven Flow
Quick answer Mutual TLS lets the server authenticate the client with a certificate instead of a bearer token, and it is notoriously awkward to configure in a GUI client. The
Read articleValidating Every Response Against the Contract vs Manual Test Scripts
Quick answer Manual test scripts assert a handful of fields you happened to think of, so they miss the drift that does not touch those fields. Validating every response against
Read articleTesting an MCP Server End-to-End Before You Publish It
Quick answer Publishing an MCP server without an end-to-end test is how you ship a tool that looks correct in the registry and fails the first time an agent calls
Read article