MCP Engineering

Build an interface that lets an agent complete the user's task, and establish where that claim holds. A correct handler is one part of the path:

authored meaning → served catalogue → receiving client → model declaration
business effect → MCP result → client/agent consumption → next model input
workflow source → published bundle → installed files → active agent context

Each arrow is a possible change in meaning, information, authority or lifetime. Inspect the arrows relevant to the task; this is not a mandate to audit everything.

Choose the work

Build: read design. Start with the user's outcome, the agent's next decisions and the boundary where authority or state changes. Choose tool operations, resource handoffs, result information and recovery from those needs. Implement the requested usable path, including ordinary consumption.

Review or repair: read review and repair. Start with the symptom and competing explanations. Find the smallest observation that separates them and reproduce the mechanism. For a review-only request, report supported findings and recommended repairs. When implementation is part of the current request or existing authorization, repair the owning layer and exercise the affected user path. Preserve intentional differences and healthy behavior.

Both: use the review route to establish the existing contract, then the build route for the part being redesigned. Do not turn a focused repair into a rewrite.

Working rules

1. Separate fact from inference. Pin the client version, receiving harness, execution mode, target and relevant capture. A server catalogue, SDK result, final model input and completed user task prove different things. A fallback observation does not silently inherit the stronger one's claim.
2. Keep semantics owned. Maintain an authoritative behavioral contract; adapt presentation where a supported receiving client demonstrably needs it. Compare from the authored source through normal activation. Hash equality can preserve an already-wrong baseline. Server validation and authorization remain effective even when a client loses guidance or ignores annotations.
3. Design information for the next decision. Discovery, detailed reads, write receipts and errors have different jobs. Keep functional handles, evidence, units, access constraints, partial-result caveats and revision guards. Neither smaller output nor structured output is automatically better.
4. Own work through settlement. An error after dispatch can mean an uncertain committed effect; a timeout can leave work running. Distinguish transport request IDs, logical operations and revision guards. Recovery, admission and resource release must follow the actual operation lifetime.
5. Use independent acceptance references. Check contract preservation, information useful to the user task, and ordinary uncoached agent behavior. Parity alone can preserve the same defect twice. A directed diagnostic is useful evidence, but is not ordinary-use acceptance.
6. Stay within the requested scope. Use existing authorization; the skill grants none. Keep load tests, paid calls, real writes, publishing and credential changes within that scope. Do not invent live evidence or demand a full fleet audit for a local fix. Healthy implementations may need no changes.

Read only what the task needs

The references describe decision criteria, not a second protocol specification. For normative behavior or SDK APIs, inspect the version in use and consult its official documentation. Prefer the maintained SDK unless a lower-level adapter is part of the requested work.

Optional offline helpers

These Python 3.10+ tools inspect local JSON without network access. Resolve their paths relative to this skill, wherever it is installed. See helper inputs and interpretation before using them.

python3 scripts/inspect_catalog.py tools-list.json
python3 scripts/compare_catalogs.py before.json after.json
python3 scripts/inspect_result.py tools-call.json

They report sizes, shapes, changes and exact parsed duplication. They do not validate business meaning, count model tokens, prove schema compatibility or establish what an agent actually saw. Their reports omit payload values by default but can contain tool names and field paths; they are not anonymizers. If no shell or captures are available, use the same reasoning directly and state which observation remains unavailable.

For substantial wording or schema reviews, use the HTML generator when a readable contract, exact comparisons and linked rationale will help the user decide. It includes the supplied values in full, unlike the summary helpers. Keep authored, served and client-visible captures explicitly labelled; a page never applies its proposal or establishes that a client saw it.

Finish with a usable result

Deliver the requested implementation or supported findings, the behavior that changed, the evidence that establishes it, and any material untested boundary. For a review, distinguish a reproduced defect from a plausible hypothesis; include the smallest useful repair. For a build, leave a working usage example and a recovery path appropriate to its effects. Do not claim deployment, installation or active-session adoption from files merely existing on disk.