Skip to content
IsoKron

MCP server builds

The ten rules for write-safe MCP servers

A write path is any tool call that changes data. Every build is designed against these ten rules; the blueprint or the scoping call says which patterns apply to your server and how.

The rules, and the finding behind each

Each rule names the public finding that motivated it, and the PostHog research-build patterns that apply it.
  1. Rule 2

    Fail-closed safety switches

    A read-only or safety setting the server does not understand stops the server. It never falls back to “writes on”.

    Motivated by github-mcp-server #3747: a read-only setting that silently stays off.

  2. Rule 3

    No credentials in model context

    Tool results never carry tokens, signed URLs or secrets. If the agent needs a file, the server fetches it.

    Motivated by github-mcp-server #3748, a hardening issue: short-lived tokenized URLs for private files in directory listings.

  3. Rule 4

    Strict schemas, no silent coercion

    A value of the wrong type is rejected with a clear error, not quietly turned into something else.

    In the research build: validate-first errors.

    Motivated by PostHog #131514: “false” stored as true, null stored as 0.

  4. Rule 5

    Batch operations

    Reading N things takes one call, not N. Fewer round trips means fewer tokens and fewer chances to fail halfway.

    In the research build: batch tools with per-item results; read-only batching.

    Motivated by our GitHub MCP server audit. Submitting a pull-request review with inline comments took 5 MCP calls; GitHub’s REST API accepts the same review, comments included, in one request.

  5. Rule 6

    Transactions where supported; honest partial failures otherwise

    Multi-resource writes use transactions where the backend supports them, otherwise explicit staging and rollback; partial outcomes are reported exactly, never as success.

    In the research build: create-with-children with rollback.

    Working example: sea-lite, our open-source work queue, lays down a batch of tickets and links in one all-or-nothing write.

  6. Rule 7

    Idempotency keys

    A write retried after a timeout is recognized and applied once, not twice.

  7. Rule 8

    Writes that return usable IDs

    Every create returns the ID of what it made, so the next call can use it without a search.

    In the research build: compact write receipts.

  8. Rule 9

    Honest annotations

    readOnlyHint, destructiveHint and idempotentHint describe what each tool actually does. They are not authorization controls: permissions are enforced by the server, not by hints.

    In the research build: confirm for destructive calls.

The patterns from the PostHog research build

The write-path and tool-design patterns a rebuild applies where the server needs them. Not every server needs every pattern; the blueprint or the scoping call says which apply.
  • Compact write receipts

    A write answers “what changed?” in a few lines: identity, version, each changed field as from and to. The full object is one flag away.

  • Batch tools with per-item results

    One call per object type instead of one per object. Every item is checked before anything is written, and each item reports its own outcome.

  • Version-checked partial updates

    A tool changes one element of an object and checks the object’s version just before writing, returning a conflict rather than overwriting a change.

  • Validate-first errors

    A failed call carries the schema of the failing field, so the agent can call first and look the schema up only when a call fails.

  • Create-with-children with rollback

    A parent and its children are created in one call that validates everything first and undoes what it wrote if a later step fails, and says so.

  • Read-only batching

    Several read-only lookups share one request; a request that holds a write is refused whole.

  • Schema de-duplication

    A repeated sub-schema is printed once, and an update tool points at its create tool’s schema when that was already shown.

  • Confirm for destructive calls

    Deletes and overwrites need an explicit confirmation, enforced by the server instead of only described.

  • Tool-name aliases (no renames)

    A guessed tool name resolves to the real tool when exactly one fits, and the unknown-tool error lists the closest real names. Nothing is renamed.

  • Per-session notes, summary fields and compact results

    Long tool notes are sent once per session, list results carry the summary an agent usually needs, and bulky query results come back as compact tables.

Packages and prices

Ready to build or rebuild your MCP server?

Share the repository or project brief and the approximate tool count. We’ll confirm the best starting point, scope, price and dates.