MCP Server Kit: a tested starter server, approval-gated write tools and a checker
by PaperChaseWebb
A small working MCP server for a made-up plumbing business where every write is a draft plus an apply that waits for the owner, an approval script the agent cannot run for you, and a read-only checker that finds unsafe tools, poisoned descriptions, open schemas, live keys and unpinned packages in any server or agent config, including starters you bought. Tested against the official MCP Python SDK with configs for Grok Bot, Claude Code, Codex and Hermes.
- Price
- $29
- Difficulty
- Intermediate
- Setup
- 30 min
- Format
- .md file
mcp-server-kit-tested-starter-approval-gated-tools-checker.md · 208 KB · instant download after checkout
Want this built for you instead? We can build it for you.
What you end up with
Your agent reads and changes real records through your own MCP server, no change lands until you approve that exact change, and every server you add has passed a check and a signed card first.
What you get
- 18 sections and an appendix in one .md file, with a one-line unpack for all 34 files
- A stdio MCP server for a made-up plumbing company: three read tools, a draft tool and an apply tool, on the 2026-07-28 protocol and the older handshake
- The two-step write: the agent drafts, the owner approves at a terminal by typing the change id, and apply refuses anything edited, stale or already applied
- mcp_check.py: 35 finding codes for tools, live probes, configs and the connect card, from poisoned descriptions and open schemas to live keys and unpinned packages
- A connect card tied to the server file's sha256, so an edit after sign-off is caught
- Configs, rules and two skills for Grok Bot, Claude Code, Codex and Hermes, six owner stops, eight prompts and a failure table
- The test harness: 56 unit tests, 292 planted faults and 39 checks against the official MCP Python SDK, so you can repeat every result
Who it is for
Anyone who wants an agent working through MCP while a person stays in charge of every change it makes.
Works with
Solid chips: the agent is named in this listing's own tools list. Dashed chip: A stdio MCP server in Python that speaks the 2026-07-28 protocol and the older handshake back to 2024-11-05, tested against the official MCP Python SDK 2.3.0. Ready configs for Claude Code (.mcp.json and permissions), Codex (config.toml) and Hermes (config.yaml), plus rules and a standing order for a Grok Bot. The configs were checked by the checker on Linux; they were not loaded inside each agent for this release.
Tools needed
Cost to run: The kit is the only purchase. Everything runs locally with Python; the checker makes no API calls.
Time to result: The checker on a server you already use in 5 minutes; the starter server connected to your agent in about half an hour
How it works
Unpack and test
Save the kit as pack.md in an empty folder, run the unpack line from section 18, then sh test_all.sh.
Expected: 34 files written; 56 tests OK; 292 of 292 planted faults caught.
Check what you already use
Run python3 mcp_check.py config on your .mcp.json, Codex config.toml or Hermes config.yaml, and probe each server you rely on.
Expected: A list of findings per server and config, or a clean line.
Connect the starter
Copy the config for your agent from configs/, point it at server/corrigan_mcp.py and run prompt 1.
Expected: The agent lists five tools and repeats the stop points.
Try the flow, then make it yours
Run prompt 6, approve the change yourself with server/approve.py, then swap the made-up jobs for your own records and sign the connect card.
Expected: One draft refused, then applied after your approval; CARD OK.
Sample prompts, free to use
Read AGENTS.md and skills/mcp-server-builder/SKILL.md. Tell me the stop points in your own words, then list the corrigan-jobs tools you can see and say which ones change anything.
Prompt 1 of 8.
Use skills/mcp-server-review. Probe [command] with no secrets set, check the tools and the config, and tell me which tools to leave off the allow list. Do not install anything else.
Prompt 4 of 8.
Draft a quote change for J-1045 to 520.00 with a reason, then call apply_change and show me the refusal. Then stop and wait for me.
Prompt 6 of 8.
Free preview of the file
# MCP Server Kit: a tested starter server, approval-gated write tools, and a checker Version 1.0, 2026-10-31. By PaperChaseWebb. A small working MCP server for a made-up plumbing business where every read is one tool and every write is a draft plus an apply that waits for the owner, the owner approval script, a read-only checker for any MCP server or agent config (yours, a bought starter, or one your agent just wrote), ready configs and rules for Claude Code, Codex, Hermes and Grok Bot, two skills, and a connect card the owner signs before an agent gets the server. Python 3.8 or later, standard library only. Tested as described in section 10: 56 unit tests and 292 planted faults on Python 3.13, 3.12, 3.11, 3.9 and 3.8, 39 of 39 checks against the official MCP Python SDK 2.3.0 in both protocol eras, and probes of three official reference servers. All business data is made up. The configs were checked by the checker, not loaded inside each agent; each gap is marked where it matters. Most MCP starter kits sell the plumbing: a template that answers tools/list, maybe auth and a Docker file. The part that hurts a small business is left to you. A tool that edits a quote or deletes a record runs the moment the agent calls it. A description in a server you installed can tell the model to do something you never asked for. A config file holds a live key and an unpinned package. This kit starts from the other end. The server is small on purpose, and its write tools cannot finish witho
Test record
- Date
- Oct 31, 2026
- What was run
- tests/test_check.py (45), tests/test_mini.py (4) and tests/test_server.py (7); tests/mutate.py with 292 cases (7 clean baselines and planted faults across tools, probes, configs, the connect card and server behavior); tests/live_sdk.py, 39 checks with the official MCP Python SDK 2.3.0 client against the server in both protocol eras; MCP Inspector 2.13.0 --cli tools/list; probes of three official reference servers; make_example.py; and the unpack line with test_all.sh. Linux, Python 3.13, 3.12, 3.11, 3.9 and 3.8.
- Result
- 56 passed, 0 failed on all five versions; 292 of 292 planted faults caught with all 7 baselines clean; 39 of 39 SDK checks; Inspector listed all five tools; the unpack line wrote 34 files and test_all.sh passed there.
- Not run
- A live Grok Bot, Claude Code, Codex or Hermes session using the server. HTTP transport or OAuth. macOS or Windows. Real business data. A full YAML parser for Hermes configs.
Copied from this item's dated test notes. What was not run stays in.
Worth knowing
- The configs and rules were checked by the checker but not loaded inside a live Grok Bot, Claude Code, Codex or Hermes session for this release. Run prompt 1 once and check the agent sees five tools and repeats the stop points before you rely on it.
- The server is stdio only. HTTP transport, OAuth and hosted servers are not included or tested.
- The approval step assumes the agent cannot run approve.py at a terminal or write the approvals folder. Run the server as a separate user or make that folder writable only by you; agent permission rules alone are not a hard boundary.
- The checker reads tool lists and config files and never calls a tool. It finds the faults it has codes for; it does not prove a server is safe. YAML configs are read with a line scan, not a full parser.
- All business data is made up. Tested on Linux only; macOS and Windows were not tested.
- On 2026-10-31 on Linux: 56 unit tests, 292 of 292 planted faults and 39 of 39 checks against the official MCP Python SDK 2.3.0 passed on Python 3.13, 3.12, 3.11, 3.9 and 3.8; MCP Inspector 2.13.0 listed the server's tools; the unpack line wrote 34 files and test_all.sh passed in that folder.
Questions
Which agents does it work with?
Any MCP client that runs stdio servers. The kit has ready configs for Claude Code, Codex and Hermes and a standing order for a Grok Bot. Those were checked by the checker, not loaded in each agent for this release.
Can my agent approve its own changes?
Not through the server. There is no approve tool, and approve.py needs a real terminal and the change id typed by hand. Run the server as a separate user so the agent cannot reach that script or folder at all.
Will the checker work on servers I already installed?
Yes. Probe any stdio server to get its tool list, or point the checker at a saved tool list or an agent config. It reads only and never calls a tool.
How is this different from the MCP server setup playbook?
The playbook helps you connect your agent to servers other people built. This kit gives you a server of your own with gated writes, and a checker for every server you add.
Can you build one for our business?
Yes. Our Install sprint builds an MCP server on your own records with the same approval step and connects your agents. Book a call or write to [email protected].
Details
Version 1.0 · Updated Oct 31, 2026 · Markdown version of this page
License: Use inside your own team or company, including on client work. Do not resell or republish the kit itself. Download terms
Related
MCP Server Kit: the two-step write pattern and a ten-check tool scan (free sample)
From MCP Server Kit: the two-step write pattern that keeps an MCP server from changing anything until the owner approves, six rules for agents that build or install servers, and a read-only script that runs ten checks on a tool list or agent config, from write tools marked read only and poisoned descriptions to live keys and unpinned packages.
MCP server setup playbook: connect your agent to real tools without handing over the keys
Pick the fewest MCP servers for a job, check them before installing, scope the credentials, configure five clients, test with MCP Inspector and build a small read-only server of your own.
Vet Before You Install: twelve checks, a sandbox recipe and a tested vetting folder for third-party agent code
Decide whether a skill, plugin, mod, MCP server, connector, repo or model gets into your agent setup: sort the seat, read every file that runs, map reach and the data path, pin and vendor it, trial it in a sandbox with a planted fake key, then record a decision the owner approves at their own terminal. v1.1 adds a seat sort before any vetting, two new checks (data path and reach, approval surfaces), evidence tiers, twelve token classes including hidden text, encoded strings, startup file edits and approval hooks, a fresh-session second read, data path questions for proxies and routers, dependency and model weight pinning, a fifth decision (not vettable) with recheck dates and an approved shelf, more special cases, a vetting folder with a fifteen-check read-only checker and an owner approval helper, agent files for Grok Bot, Claude Code, Codex and Hermes, and twelve new prompts (27 in all). Price unchanged.
Reach Inventory: every connector your agents hold, with a job, an owner and a way out
One row for every connector, MCP server, OAuth grant, API key and automation bridge your agents can use, each tied to a job and marked necessary, convenient or leftover. Scope granted is set against the scope the job needs, keys are named by where they live and never pasted, bridges list every app behind them, and leftover access is removed with a date and proof. Agents list and propose; removals, narrower scopes, rotations and new grants wait for your yes at your own terminal, tied to the sha256 of the inventory. Fifteen read-only checks run on the inventory.
Shrink the Attack Surface: patch with proof, then attack your own agent's tools
Your agent lists everything your app exposes, read-only: routes, open ports, public buckets, secrets in the repo, unused dependencies, debug endpoints, admin paths, CORS, API key scopes and its own tool permissions. You decide keep, remove or lock for each. Every fix gets a proof that fails before the change and passes after it, and the proof stays as a regression test. Then attack drills run against your agent's own tool gate, offline: pressure, impersonation, injected tool output, stale and non-owner approvals and a failing tool. Each is judged by what the tools actually did, and every drill that gets through becomes a test that fails before the fix and passes after. A failing tool stops at a retry budget and asks you, and every approval is yours, typed at your own terminal and tied to a sha256.
Ask-first rules for AI agents: hard nos, approval cards and a test set
Paste-in rules that make an agent ask before it sends, spends, posts or deletes, define what a real yes is, and stop retries after a no, plus 12 test scenarios to check it.
Design MCP tools and errors so the model's next call is the right one
Two MCP server builders shared numbers and rules from real use. A Photoshop server with 83 tools kept model-caused bad calls to about 1 in 290 by making every tool distinct, folding variants into parameters, returning errors that list allowed values, and giving the model a short capability map. A design editor server added batch writes with one undo step and idempotency keys that report stale after an undo.
Sandbox your MCP servers too, because the agent's sandbox may not cover them
A write-up on r/mcp points out that Claude Code's and Codex's own docs say local MCP servers run as ordinary processes outside the agent's sandbox. It walks through a recent paper on narrow tools being steered into reading files outside their job, and gives concrete container and environment settings.