{"slug": "show-hn-stepgate-an-mcp-server-that-won-t-let-agents-skip-steps", "title": "Show HN: Stepgate – an MCP server that won't let agents skip steps", "summary": "Stepgate, an MCP server released on Hacker News' Show HN, runs agent procedures written as YAML \"stepfiles\" and shows the calling agent one step at a time, advancing only when that step's gates pass. Each stepfile declares its inputs, the remote APIs and MCP servers it may call, and an ordered step list, naming no model or framework; Stepgate itself makes the required API calls, such as looking up npm package versions from the registry, and gates reject output that violates JSON Schema, JSONLogic or an HTTP verifier. The tool is positioned as an alternative to markdown skills and runbooks, where the agent decides how much of a plan to follow and nothing records what actually ran.", "body_md": "**Agents can't skip steps.** Write an agent's procedure once, as a YAML stepfile, and run it from any MCP client, such as Claude Code, with the model that client already uses.\n\nA **stepfile** declares its inputs, the remote APIs and MCP servers it may call, and an ordered list of steps. Each step says what output it must produce and which **gates** check that output. The file names no model and no framework.\n\n**Stepgate** runs stepfiles. It is an MCP server that offers each stepfile as a tool. When a client's agent calls it, Stepgate shows the agent one step at a time, makes every API call the step needs, and moves on only when the step's gates pass.\n\nA skill or runbook written as markdown tells an agent what to do, and the agent decides how much of it to follow. Here is one:\n\n```\n---\nname: package-notes\ndescription: Writes an upgrade note for each npm package, with versions taken from the registry.\n---\n1. Look up each package's latest version on the npm registry.\n2. Write a one-line upgrade note for each. Never state a version the registry did not return.\n```\n\n`stepgate_outline` turns it into a skeleton, and the finished stepfile makes both lines binding. Stepgate does the lookup itself, so the agent never fetches or copies a version. The agent only writes the notes, and a gate rejects any note whose version differs from what the registry returned, naming the rows that broke it:\n\n```\nstepgate: \"1\"\nid: package-notes\ndescription: Writes an upgrade note for each npm package, with versions taken from the registry.\ninputs:\n  type: object\n  required: [packages]\n  properties:\n    packages: { type: array, minItems: 1, maxItems: 20, items: { type: string, pattern: \"^[a-z0-9][a-z0-9._-]*$\" } }\ntools:\n  npm:\n    openapi:\n      server: https://registry.npmjs.org\n      document:\n        openapi: 3.1.0\n        info: { title: npm registry, version: \"1\" }\n        paths:\n          /{name}/latest:\n            get:\n              operationId: getLatest\n              parameters: [{ name: name, in: path, required: true, schema: { type: string } }]\n    exposes: [getLatest]\nsteps:\n  - id: look-up\n    do:\n      calls:\n        - id: latest\n          operation: getLatest\n          each: { var: inputs.packages }\n          arguments: { name: { var: item } }\n      output:\n        packages: { map: [{ var: responses.latest }, { object: [[name, { var: name }], [latest, { var: version }]] }] }\n    produces:\n      type: object\n      required: [packages]\n      properties: { packages: { type: array } }\n  - id: notes\n    instructions: |\n      Write a one-line upgrade note for each of these packages, saying what\n      its latest version is and whether that is a new major version:\n\n      {{steps.look-up.packages}}\n    produces:\n      type: object\n      required: [notes]\n      properties:\n        notes:\n          type: array\n          items:\n            type: object\n            required: [name, latest, note]\n            properties: { name: { type: string }, latest: { type: string }, note: { type: string } }\n    gates:\n      - id: versions-from-registry\n        message: Every note must give the version the registry returned for its package.\n        predicate:\n          none:\n            - join: [{ var: output.notes }, { var: steps.look-up.packages }, name, name]\n            - or: [{ \"==\": [{ var: right }, null] }, { \"!=\": [{ var: left.latest }, { var: right.latest }] }]\n    retries: 2\n```\n\nWhen an agent is handed a plan as text, it decides how much of the plan to follow, a step counts as done when the agent says so, and nothing records afterwards what actually ran. A stepfile moves those decisions out of the model:\n\n- **Steps run in order, one at a time.** The agent is shown only the current step's instructions and operations, never a later step, so it cannot skip ahead. Earlier steps stay in its own conversation.\n- **Gates decide, not the model.** A step passes only when its output satisfies JSON Schema, JSONLogic or an HTTP verifier, and gates can check that output against what the APIs actually returned, so a fabricated value fails. A failed gate's diagnosis goes back to the model for a bounded number of retries.\n- **The model never holds a key.** The server makes every tool call and attaches credentials itself, and it refuses requests to hosts the stepfile does not declare.\n- **Every run leaves a record.** A hash-chained ledger lists each step, tool call, gate verdict and retry, and editing it afterwards breaks the chain, which`stepgate --verify` detects.\n- **Nothing to install on the client side.** Stepfiles call remote APIs only, and the client adds one MCP server to its configuration. Stepgate needs no model key: the client's own model does the reasoning.\n\nAdd the server to your MCP client's configuration, naming one or more stepfiles from the [catalog](https://github.com/Chaarangan/stepgate/blob/main/stepfiles), or giving absolute paths to your own `.stepfile.yaml` files ([details](https://github.com/Chaarangan/stepgate/blob/main/docs/connect.md#your-own-stepfiles)):\n\n```\n{\n  \"mcpServers\": {\n    \"stepgate\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"stepgate\", \"market-research\"],\n      \"env\": { \"TAVILY_API_KEY\": \"tvly-...\" }\n    }\n  }\n}\n```\n\nThe client sees a `market-research` tool. Ask your agent to run it for `{ \"brand\": \"Oatly\", \"market\": \"UK plant-based milk\" }` and it works through four steps (search, filter, analyse, report) with `stepgate_call` and `stepgate_submit`, ending with every step's output. [docs/connect.md](https://github.com/Chaarangan/stepgate/blob/main/docs/connect.md) has the configuration for Claude Code, Claude Desktop, Cursor, VS Code and other clients.\n\nEvery server also offers tools for writing stepfiles: ask your agent to write one for your use case, and it can read the format, inspect the APIs, validate its draft and try it through Stepgate ([details](https://github.com/Chaarangan/stepgate/blob/main/docs/connect.md#writing-stepfiles-with-an-agent)).\n\nTo serve over HTTP instead of stdio, run `npx -y stepgate --http 3100 market-research` and connect to `http://127.0.0.1:3100/mcp`. `npx -y stepgate --list` shows the catalog, and `--help` lists the limits and the `--ledger-dir` option.\n\n```\nstepgate: \"1\"\nid: market-research\ninputs:\n  type: object\n  required: [brand, market]\n  properties:\n    brand: { type: string }\n    market: { type: string }\n\ncredentials:\n  tavily:\n    kind: bearer\n    hosts: [mcp.tavily.com]\n    description: Web search, used only by the search step.\n\ntools:\n  tavily:\n    mcp: { url: \"https://mcp.tavily.com/mcp/\" }\n    credential: tavily\n    exposes: [tavily_search]\n\nsteps:\n  - id: search\n    tools: [tavily_search]\n    instructions: |\n      Run at least six searches about {{inputs.brand}} in {{inputs.market}}.\n      Submit every result as a source with an id of the form S-01.\n    produces:\n      type: object\n      required: [sources]\n      properties:\n        sources: { type: array }\n    gates:\n      - id: enough-sources\n        schema: { properties: { sources: { minItems: 12 } } }\n      - id: domain-breadth\n        message: Sources must span at least six distinct domains.\n        predicate:\n          \">=\":\n            - { length: { unique: { map: [{ var: output.sources }, { host: { var: url } }] } } }\n            - 6\n    retries: 2\n  # ... filter, analyse and report steps\n```\n\nCredentials say what is needed, never where it lives: the server reads `tavily` from `TAVILY_API_KEY`. The complete file is [stepfiles/marketing/market-research](https://github.com/Chaarangan/stepgate/blob/main/stepfiles/marketing/market-research), and editors that support `yaml-language-server` validate against [server/schema/stepfile.schema.json](https://github.com/Chaarangan/stepgate/blob/main/server/schema/stepfile.schema.json), which the npm package also ships.\n\n[stepfiles/](https://github.com/Chaarangan/stepgate/blob/main/stepfiles) is a community catalog of stepfiles, reviewed and shipped with the npm package, so each one runs by name. Built something repeatable? Adding it is one folder and one pull request: see [stepfiles/README.md](https://github.com/Chaarangan/stepgate/blob/main/stepfiles/README.md), or [suggest an idea](https://github.com/Chaarangan/stepgate/issues/new?template=stepfile_idea.yml).\n\n- [docs/stepfile.md](https://github.com/Chaarangan/stepgate/blob/main/docs/stepfile.md) : how to write a stepfile: fields, tools, credentials, steps and gates.\n- [docs/connect.md](https://github.com/Chaarangan/stepgate/blob/main/docs/connect.md) : connecting Claude Code, Claude Desktop and other MCP clients.\n- [docs/how-it-works.md](https://github.com/Chaarangan/stepgate/blob/main/docs/how-it-works.md) : what Stepgate does during a run, its limits, errors and ledger.\n- [server/schema/stepfile.schema.json](https://github.com/Chaarangan/stepgate/blob/main/server/schema/stepfile.schema.json) : the JSON Schema for stepfiles.\n- [CONTEXT.md](https://github.com/Chaarangan/stepgate/blob/main/CONTEXT.md) : the project's vocabulary.\n\nSee [CONTRIBUTING.md](https://github.com/Chaarangan/stepgate/blob/main/CONTRIBUTING.md). To report a vulnerability, follow [SECURITY.md](https://github.com/Chaarangan/stepgate/blob/main/SECURITY.md). Everyone taking part is expected to follow the [Code of Conduct](https://github.com/Chaarangan/stepgate/blob/main/CODE_OF_CONDUCT.md).", "url": "https://wpnews.pro/news/show-hn-stepgate-an-mcp-server-that-won-t-let-agents-skip-steps", "canonical_source": "https://github.com/Chaarangan/stepgate", "published_at": "2026-09-28 00:57:31+00:00", "updated_at": "2026-09-28 01:31:03.802385+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools"], "entities": ["Stepgate", "MCP", "Claude Code", "npm"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-stepgate-an-mcp-server-that-won-t-let-agents-skip-steps", "markdown": "https://wpnews.pro/news/show-hn-stepgate-an-mcp-server-that-won-t-let-agents-skip-steps.md", "text": "https://wpnews.pro/news/show-hn-stepgate-an-mcp-server-that-won-t-let-agents-skip-steps.txt", "jsonld": "https://wpnews.pro/news/show-hn-stepgate-an-mcp-server-that-won-t-let-agents-skip-steps.jsonld"}}