Builder Toolkit: Checks, MCP Server and Agent Instructions

Purpose: Put the wiki's controls, risks and test cases where code is written, in a form that works the same whichever assistant, agent, editor, operating system or CI service a team uses.

Audience: AI product developers, application security engineers, DevSecOps and platform engineers. Governance teams can use the evidence export without running anything else.

How to use: Copy the files from the code/ folder into a tools/ folder in your repository. Run the checker, wire it into git hooks and CI, connect the MCP server to your assistant if it supports MCP, and write the instruction files into your repository. Each section below says how.

The one idea

The checks are code, not prompts. Anything that must give the same answer every time (does this line pass model output to eval, is this MCP server pinned, which controls does AI-R23 map to) runs in a small Python program with tests. An assistant can call it and explain the result, but it does not decide the result. So Claude, ChatGPT, Gemini, Copilot, Cursor, any other assistant, or a person at a terminal all get the same findings, and CI enforces them whoever wrote the code.

Every tool uses only the Python standard library (3.10 or later), so there is nothing to install. The toolkit's tests, and the rest of the Builder Track's, run on Linux, macOS and Windows on every change (Builder Track tests workflow).

What is in the toolkit

How it fits with ai-secure-by-design

Ankush Jain's ai-secure-by-design (v0.2, commit 70ef026, 24 October 2026) is a platform-neutral engine for secure and private development: NIST SSDF, ISO/IEC 27001 and India's DPDP Act, with code scaffolds for consent, data principal rights, audit logging and human oversight. This toolkit does not repeat it. It adds what that engine leaves out: AI-specific rules (what happens to model output, how models and MCP servers are loaded) and look-ups into this wiki's controls, risks and test cases.

The two follow the same conventions, so they can run side by side in the same hooks and CI job:

The comparison is from reading that repository's files on 29 October 2026; it may have changed since.

The checker

python tools/aiwiki_check.py src/ config/              # files or folders
python tools/aiwiki_check.py --staged                  # only lines added in the staged change
python tools/aiwiki_check.py --diff origin/main        # only lines added since a base (CI)
python tools/aiwiki_check.py --stdin --filename app.py < new_content.py   # content an agent is about to write
python tools/aiwiki_check.py . --format sarif --output aiwiki.sarif --fail-on MEDIUM

Use python3 where python is not on the path. Exit codes are 0 for no findings at or above --fail-on (default HIGH), 1 for findings, and 2 for a usage or runtime error. To accept one line after review, add a comment containing aiwiki: ignore AIW-004 (or aiwiki: ignore for every rule) and record why.

The MCP rules read JSON configuration files that hold an mcpServers, servers or mcp.servers object, which covers the layouts several clients use. AIW-010 matches flag and setting names taken from several vendors' coding agents. Both lists come from documentation as of mid-2026 and were not re-checked for this page, so check your own tools' current names and add any that are missing to ai_rules.json.

To add a rule, add an entry to ai_rules.json with a pattern, the controls it supports and the test cases that prove the fix. The tests check that every control, risk and test case a rule names exists in the wiki.

The MCP server

The Model Context Protocol is an open protocol that many assistants, agents and editors use to call tools. Any client that supports MCP can use this server; nothing in it is specific to one vendor.

It also offers one prompt, review-agent-design, which asks the assistant to review a design against the ten controls in Secure Your First Agent using the tools for IDs.

Every tool is read-only: none writes files, runs commands or reaches the network. Most local clients take a configuration entry of this shape (the outer key, such as mcpServers or servers, and the file it lives in differ by client, so check yours):

{
  "mcpServers": {
    "ai-security-wiki": {
      "command": "python",
      "args": ["tools/mcp_server.py", "--data", "tools/data"]
    }
  }
}

--data points at a folder holding the wiki's CSV files. Without it, the server looks for the 25_Templates/data folder next to the Builder Track, which is where it is when you run it from a copy of this wiki.

HTTP mode. python tools/mcp_server.py --http serves the same tools at http://127.0.0.1:8765/mcp. It answers JSON over HTTP POST and does not open a server-sent event stream. It refuses to listen on any address other than loopback unless a bearer token is set (--token, or the AIWIKI_MCP_TOKEN environment variable), and it rejects requests whose Host or Origin header is not on its allow-list (--allow-host). Hosted assistants that can only reach remote servers need it published behind TLS and your own authentication; this reference does not provide that.

The server answers MCP protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05. The tests drive it with JSON-RPC messages written from the specification, not with a vendor's client, so check it with your own client before relying on it.

Look-ups from the command line

python tools/wiki_data.py control AI-CTRL-024
python tools/wiki_data.py risk AI-R23
python tools/wiki_data.py test TC-L06-008
python tools/wiki_data.py search "kill switch" --kind control

The answers come from the CSV files, which the wiki rebuilds from its pages on every build. The pages remain authoritative, and every answer includes the page's URL.

Evidence for the templates

evidence_export.py reads the guard's hash-chained audit log and any SARIF file, and writes two CSV files:

python tools/evidence_export.py --audit-log audit.jsonl --sarif aiwiki.sarif \
    --controls controls_evidence.csv --tests test_evidence.csv

• --controls has one row per control, using the column names of the Controls sheet in the AI Security Audit and Evidence Checklist: Control ID, Control, Result, Evidence Ref, Evidence Collection Date and Auditor Notes.
• --tests has one row per test case, using the Test Case Tracker's Date Run, Evidence Ref and Notes columns.

Each evidence reference includes the input file's SHA-256 prefix, so a reviewer can tell which file a row came from. The tool first checks the log's hash chain and says in the notes whether it holds; it exits with code 1 if a log has been edited. It records what was observed, not a verdict: a denied call shows that a control acted at least once, not that it is effective. Result and Score are left for the reviewer. The guard's decisions map to controls and test cases as in the Prove it table.

One set of instructions for every assistant

agent_instructions.txt holds the rules a coding assistant should follow in a repository that builds AI features: treat model output as untrusted, enforce tool calls outside the model, ask before sensitive actions, sandbox generated code, pin models and MCP servers, run the checks before saving a file, and cite only wiki IDs it has looked up. gen_instructions.py writes it into your repository as each assistant's own file:

python tools/gen_instructions.py --out .            # AGENTS.md, CLAUDE.md, GEMINI.md, Copilot and Cursor files
python tools/gen_instructions.py --out . --check    # in CI: fail if a file is missing or out of date

Which file each tool reads is from documentation as of mid-2026 and changes often; check each tool's current documentation. Existing files are never overwritten unless you pass --force, because they may hold your own instructions. Instructions guide an assistant; they do not enforce anything. The checks in git hooks and CI are the control.

Wire it into hooks and CI

Each agent passes data to its hooks in a different format, so this page does not ship an adapter per agent. Where the agent supports MCP, the check_ai_code tool does the same job. As Developer Pipeline Checks explains, only the CI layer is a control; make the check required in branch protection.

Run it

From the code/ folder, with Python 3.10 or later:

python -m unittest -v test_toolkit      # the toolkit tests (any operating system)
python aiwiki_check.py .                 # the reference code is clean; the test fixtures are not

Prove it

• Commit a line such as exec(llm_output) with the hooks installed, and again with --no-verify. The first must be blocked locally, the second in CI (TC-L05-015).
• Add an MCP server to your client's configuration as npx -y some-server. The checker must report AIW-007, and your tool inventory must record the pinned version you replace it with (TC-L06-037).
• Run the evidence export on a guard log, change one line of the log, and run it again. The second run must report the broken chain (TC-L17-020).

Limits of this reference

Verify before use: The rules are line-based pattern checks. They miss model output that passes through a variable with an unrelated name, and they can flag safe code; treat each finding as a prompt for a reviewer, and a clean result as no proof of safety. The MCP server has not been tested with any particular vendor's client. HTTP mode is for local use and has no TLS. Client configuration formats, instruction-file locations and agent flag names change often, and the ones on this page were not re-checked against each vendor's current documentation. All the Builder Track tests, including the toolkit's, run on Linux, macOS and Windows.

Related pages

• Secure Your First Agent and Agent Architecture Patterns
• Developer Pipeline Checks
• AI Coding Assistant and Coding Agent Security Standard
• OWASP MCP Top 10 Crosswalk and NIST SSDF Crosswalk
• Templates and CSV data files