The Powerduck Blog
Product updates, engineering notes, and guides for designing, debugging, testing, mocking, and serving MCP tools from one OpenAPI spec.
Browse the guidesIntegration is done and the partner asks for a link. Finish descriptions locally, verify real calls, and publish versioned hosted docs and MCP from the same workspace, with no doc-tool rollout attached.
Read articleTwo hundred routes, an Express and two FastAPI services, and a Postman collection from 2023. An AST scan reconstructs the real contract, marks honest gaps instead of guessing, and stays repeatable through rescans.
Read articleDocs, mock, and MCP endpoint usually mean three pipelines, three versions, and three sources of drift. Here is how to publish human docs and an agent endpoint from one OpenAPI document on your own domain, with access control, versioning, and a rollback path.
Read articleFunction calling is a model capability; plugins were a ChatGPT-era distribution experiment; MCP is a transport and discovery protocol between clients and tool servers. They are not competitors, and confusing them produces bad integrations. Here is the layered view and where your OpenAPI spec fits.
Read articleInventory APIs get consumed by developers reading docs and by agents discovering tools. Separate web docs, prompt pastes, and hand-written schemas guarantee drift; one OpenAPI file produces both.
Read articlePostman made collections the source of truth and put them in the cloud. A newer workflow makes the OpenAPI spec the source, keeps files on disk where git can see them, and treats debugging, mocks, tests, and MCP as views over one document. Here is an honest comparison.
Read articleA concrete Cloud walkthrough: publish a managed Streamable HTTP MCP endpoint from one spec, expose twelve operations out of forty-seven, gate agents with a rotated bearer key, inject upstream auth, and pin the partner to an immutable version.
Read articlePasted docs rot mid-session, burn tokens on every conversation, and leave the agent guessing field names. An MCP server generated from the OpenAPI spec gives an agent callable tools with typed inputs instead of prose. Here is when that wins and when it does not.
Read articleHand-writing tool wrappers around existing order and inventory endpoints means maintaining every contract twice. Generate the MCP server from the OpenAPI spec, start with read-only tools, and widen the surface deliberately.
Read articleA curl command captures one request perfectly and everything else not at all. Postman collections capture folders and auth but lose response schemas. Here is a field-by-field mapping, what every converter drops, and a workflow that ends with a maintained spec.
Read articleConsumer-driven contracts with Pact are powerful but bring a broker, pactfiles, and a workflow small teams never maintain. Here is what contract testing is really protecting, and a lighter OpenAPI-based setup that catches the same integration bugs with tools you already run.
Read articleA real integration walkthrough: import the vendor OpenAPI file once, let the assistant and your coding agent read the exact contract, and send real requests locally, with no more curl archaeology in chat windows.
Read article