The Powerduck Blog
Product updates, engineering notes, and guides for designing, debugging, testing, mocking, and serving MCP tools from one OpenAPI spec.
Browse the guidesVersioning is less about where the number goes than about knowing what actually breaks a client and communicating the sunset. Here is the honest tradeoff between path and header versioning, a breaking-change checklist, and how to enforce it with OpenAPI diffs in CI.
Read articleMost OpenAPI auth docs are subtly wrong: a scheme is defined but never applied, a token is modeled as a plain header, or OAuth scopes do not match the server. Here is how to document each mechanism correctly, combine them with AND/OR semantics, and mark public endpoints.
Read articleInline every schema and your request and response models drift apart. Extract everything and the document becomes a maze of one-off references. The middle path is a small set of rules for what becomes a component, what stays inline, and how to name and compose it.
Read articleAsking an LLM to read your whole codebase and emit OpenAPI produces fluent, non-reproducible fiction. Pure AST scanning is reproducible but goes blind on dynamic serializers. The reliable design is static analysis first, with AI filling only proven gaps a human can review.
Read articleFastAPI puts contracts in annotations; Django REST puts them in serializers and viewsets. A static scanner can recover both without a running server, but the dynamic parts of DRF, external models, source mappings, and runtime choices, must be reported as gaps rather than turned into invented enums.
Read articleExpress has no built-in schema layer and NestJS Swagger decorators drift the moment a DTO changes. A deterministic scanner can prove routes from the real framework instance and recover schemas from TypeScript types, leaving explicit, reviewable gaps instead of guesses.
Read articleYou do not need to rewrite a working HTTP service as an agent framework to be reachable over A2A. A thin, stateless adapter can expose one authenticated business handler as JSON-RPC, REST, and native gRPC, while being honest about which agent capabilities it does not provide.
Read articleAn Agent Card is the public resume of an A2A agent: where it lives, which bindings it speaks, and what skills it offers. Fetching it is easy; trusting it is the part teams get wrong. Here is how discovery and signature verification actually work.
Read articleMCP connects one agent to tools and data. A2A connects autonomous agents to each other through discoverable, long-lived tasks. They are not competitors; they sit at different layers, and getting the boundary wrong is where agent architectures become unmaintainable.
Read articleFree-form tool arguments are where agent workflows break: the model invents fields, sends numbers as strings, and omits required values. Structured outputs backed by strict JSON Schema make tool calls deterministic, and most of that schema already exists in your OpenAPI components.
Read articlePointing an agent at forty internal MCP servers breaks tool limits and buries it in duplicated names. The pattern that works at scale is one authenticated gateway that aggregates specs, namespaces the tools, and keeps auth, logging, and rate limits in one place.
Read articleMCP turns external content into actions: a tool description or API response is text the model reads and trusts, which makes indirect prompt injection a real attack path. Here is a practical threat model and the controls that actually work, from scoped tokens to human-in-the-loop and audit logs.
Read article