The Powerduck Blog
Product updates, engineering notes, and guides for designing, debugging, testing, mocking, and serving MCP tools from one OpenAPI spec.
Browse the guidesMost teams expose everything as MCP tools and end up with a catalog the model cannot navigate. The protocol defines three primitives for a reason: tools act, resources are readable context, and prompts package reusable workflows. Here is how to decide, with examples from an API platform.
Read articleAgents discover MCP tools at runtime and learn names and parameters from descriptions, so a renamed tool is a silent production break. Here is how to evolve a tool catalog: additive changes, deprecation windows, versioned names as a last resort, and CI diffs from the source spec.
Read articleEvery AI editor now speaks MCP, but each one stores config differently, supports different transports, and has its own OAuth quirks. This is the practical comparison: where the config lives, what works over stdio vs HTTP, and the gotchas for six mainstream clients.
Read articleHuman callers read prose and ask a teammate when confused; agents retry, chain calls, and act on whatever a response most resembles. A few design rules separate APIs agents use reliably from ones they misuse: idempotency, strict schemas, machine errors, and async jobs.
Read articleAn MCP server is just JSON-RPC over a transport, which means it is fully testable without an AI in the loop. Here is a practical ladder: Inspector for discovery, curl for the protocol, and deterministic automated tests for schemas, errors, and side effects in CI.
Read articleThe same MCP server can run over stdio on a laptop or Streamable HTTP behind a domain, and the choice changes auth, state, latency, and who can use it. Here is a decision framework with the actual launch commands and client config for each transport.
Read articleLocal stdio MCP servers inherit your CLI credentials, so nobody notices auth until they host one. Remote MCP servers require OAuth 2.1 with PKCE, metadata discovery, and short-lived tokens. Here is the full flow and the mistakes that get servers rejected by clients.
Read articleStop pasting internal API docs into every agent session. Serve the OpenAPI spec as a local or hosted MCP endpoint, register it once in Cursor and Claude Code, and let the agent call typed tools. Here is the full setup, auth scoping, and the verification checklist.
Read articleA scanned document is only worth something if the team exercises it. Start a mock for blocked consumers, chain real scenario tests against staging, and serve the spec as an MCP server for internal agents.
Read articleAgents guess field names when they never see the contract. Serve the spec over MCP, generate one verified vertical slice at a time, run scenarios against localhost, and rescan to catch drift.
Read articleBehavior first, routes second. AI drafts the OpenAPI contract as reviewable diffs, the team settles money, idempotency, and error envelopes up front, and mocks plus scenarios define done before implementation starts.
Read articleA concrete audit of where requests, model calls, database queries, mock traffic and license checks run in the Powerduck desktop app, and what the network can and cannot see.
Read article