Content
<a id="readme-top"></a>
<div align="center">
<img src="docs/images/banner.svg" alt="Stepgate: agents can't skip steps" width="100%" />
<p align="center">
[![CI][ci-shield]][ci-url]
[![npm][npm-shield]][npm-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![License: Apache-2.0][license-shield]][license-url]
</p>
<p align="center">
Write an agent's procedure once, as a YAML stepfile, and every step is gated.
<br />
<a href="docs/stepfile.md"><strong>Read the stepfile format »</strong></a>
<br />
<br />
<a href="#quick-start">Quick start</a>
·
<a href="awesome-stepfiles/">Browse the catalog</a>
·
<a href="https://github.com/Chaarangan/stepgate/issues/new?template=bug_report.yml">Report a bug</a>
·
<a href="https://github.com/Chaarangan/stepgate/issues/new?template=feature_request.yml">Request a feature</a>
</p>
</div>
<details>
<summary>Table of contents</summary>
<ol>
<li>
<a href="#about-the-project">About the project</a>
<ul>
<li><a href="#why">Why</a></li>
<li><a href="#built-with">Built with</a></li>
</ul>
</li>
<li>
<a href="#getting-started">Getting started</a>
<ul>
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#quick-start">Quick start</a></li>
</ul>
</li>
<li>
<a href="#usage">Usage</a>
<ul>
<li><a href="#a-stepfile">A stepfile</a></li>
<li><a href="#make-the-procedure-you-already-wrote-enforceable">Make the procedure you already wrote enforceable</a></li>
<li><a href="#create-your-stepfile">Create your stepfile</a></li>
<li><a href="#command-line">Command line</a></li>
</ul>
</li>
<li><a href="#catalog">Catalog</a></li>
<li><a href="#documentation">Documentation</a></li>
<li>
<a href="#contributing">Contributing</a>
<ul>
<li><a href="#contributors">Contributors</a></li>
</ul>
</li>
<li><a href="#license">License</a></li>
<li><a href="#contact">Contact</a></li>
<li><a href="#acknowledgments">Acknowledgments</a></li>
</ol>
</details>
## About the project
**Agents can't skip steps.** The agent moves on only when a mechanical check passes, never on its own word. Stepgate is for anyone running agents on procedures where a skipped step or an invented value costs something, such as a cited research report, a CVE triage or a ticket written to Jira.
**One file runs anywhere.** A stepfile has no packages, no versions to pin and no code to deploy, so it moves as a single file to any MCP client, such as Claude Code, Cursor or an agent you wrote, and runs on the model that client already uses.
A **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.
**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.
### Why
When 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:
- **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.
- **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.
- **The model judges, the server computes.** A mechanical step makes its API calls and builds its output from a template, with no model involved, and a derived field fills in a count or a lookup after the model submits. The model is left the work that needs judgement.
- **Writes wait for a person.** An approve gate asks a person to confirm a step's output through an MCP elicitation before a later mechanical step writes it, so what reaches Jira is what the person saw ([which clients show the form](docs/connect.md#approvals)).
- **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.
- **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.
- **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, and the same file gives the same path through its steps whichever model that is.
<p align="right">(<a href="#readme-top">back to top</a>)</p>
### Built with
* [![TypeScript][typescript-shield]][typescript-url]
* [![Node.js][node-shield]][node-url]
* [![Model Context Protocol][mcp-shield]][mcp-url]
* [![JSON Schema][jsonschema-shield]][jsonschema-url] with [Ajv](https://ajv.js.org/)
* [![JSONLogic][jsonlogic-shield]][jsonlogic-url]
<p align="right">(<a href="#readme-top">back to top</a>)</p>
## Getting started
### Prerequisites
* An MCP client, such as Claude Code, Claude Desktop, Cursor or VS Code.
* Node.js 22.18 or later, so the client can start Stepgate with `npx`.
* The credentials your stepfile declares. The `market-research` example below needs a [Tavily](https://tavily.com/) API key.
### Quick start
1. Add the server to your MCP client's configuration, naming one or more stepfiles from the [catalog](awesome-stepfiles/), or giving absolute paths to your own `.stepfile.yaml` files ([details](docs/connect.md#your-own-stepfiles)):
```json
{
"mcpServers": {
"stepgate": {
"command": "npx",
"args": ["-y", "stepgate", "market-research"],
"env": { "TAVILY_API_KEY": "tvly-..." }
}
}
}
```
2. The client sees a `market-research` tool. Ask your agent to run it for `{ "brand": "Oatly", "market": "UK plant-based milk" }`.
3. The agent works through four steps (search, filter, analyse, report) with `stepgate_call` and `stepgate_submit`, and the run ends with every step's output.
[docs/connect.md](docs/connect.md) has the configuration for Claude Code, Claude Desktop, Cursor, VS Code and other clients.
Every 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](docs/connect.md#writing-stepfiles-with-an-agent)).
<p align="right">(<a href="#readme-top">back to top</a>)</p>
## Usage
### A stepfile
```yaml
stepgate: "1"
id: market-research
inputs:
type: object
required: [brand, market]
properties:
brand: { type: string }
market: { type: string }
credentials:
tavily:
kind: bearer
hosts: [mcp.tavily.com]
description: Web search, used only by the search step.
tools:
tavily:
mcp: { url: "https://mcp.tavily.com/mcp/" }
credential: tavily
exposes: [{ name: tavily_search, effect: read }]
steps:
- id: search
tools: [tavily_search]
instructions: |
Run at least six searches about {{inputs.brand}} in {{inputs.market}}.
Submit every result as a source with an id of the form S-01.
produces:
type: object
required: [sources]
properties:
sources: { type: array }
gates:
- id: enough-sources
schema: { properties: { sources: { minItems: 12 } } }
- id: domain-breadth
message: Sources must span at least six distinct domains.
predicate:
">=":
- { length: { unique: { map: [{ var: output.sources }, { host: { var: url } }] } } }
- 6
retries: 2
# ... filter, analyse and report steps
```
Credentials say what is needed, never where it lives: the server reads `tavily` from `TAVILY_API_KEY`. `effect: read` marks the search as safe to retry. The complete file is [awesome-stepfiles/marketing/market-research](awesome-stepfiles/marketing/market-research/), and editors that support `yaml-language-server` validate against [server/schema/stepfile.schema.json](server/schema/stepfile.schema.json), which the npm package also ships.
### Make the procedure you already wrote enforceable
A 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:
```markdown
---
name: package-notes
description: Writes an upgrade note for each npm package, with versions taken from the registry.
---
1. Look up each package's latest version on the npm registry.
2. Write a one-line upgrade note for each. Never state a version the registry did not return.
```
`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.
<details>
<summary>The finished <code>package-notes</code> stepfile</summary>
```yaml
stepgate: "1"
id: package-notes
description: Writes an upgrade note for each npm package, with versions taken from the registry.
inputs:
type: object
required: [packages]
properties:
packages: { type: array, minItems: 1, maxItems: 20, items: { type: string, pattern: "^[a-z0-9][a-z0-9._-]*$" } }
tools:
npm:
openapi:
server: https://registry.npmjs.org
document:
openapi: 3.1.0
info: { title: npm registry, version: "1" }
paths:
/{name}/latest:
get:
operationId: getLatest
parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
exposes: [getLatest]
steps:
- id: look-up
do:
calls:
- id: latest
operation: getLatest
each: { var: inputs.packages }
arguments: { name: { var: item } }
output:
packages: { map: [{ var: responses.latest }, { object: [[name, { var: name }], [latest, { var: version }]] }] }
produces:
type: object
required: [packages]
properties: { packages: { type: array } }
- id: notes
instructions: |
Write a one-line upgrade note for each of these packages, saying what
its latest version is and whether that is a new major version:
{{steps.look-up.packages}}
produces:
type: object
required: [notes]
properties:
notes:
type: array
items:
type: object
required: [name, latest, note]
properties: { name: { type: string }, latest: { type: string }, note: { type: string } }
gates:
- id: versions-from-registry
message: Every note must give the version the registry returned for its package.
predicate:
none:
- join: [{ var: output.notes }, { var: steps.look-up.packages }, name, name]
- or: [{ "==": [{ var: right }, null] }, { "!=": [{ var: left.latest }, { var: right.latest }] }]
retries: 2
```
</details>
### Create your stepfile
Ask your coding assistant for one in plain words. With Stepgate connected, it reads the format, inspects the API, validates its draft and tries it:
```text
Write a stepfile that converts an amount between currencies at the latest ECB rate,
using the Frankfurter API. Try it with 250 USD to EUR.
```
For the full prompt and the files to point it at, see [the prompt](awesome-stepfiles/README.md#the-prompt) in the catalog.
### Command line
To 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 every option, including these:
| Option | What it does |
|---|---|
| `--watch` | Reloads your stepfiles when you save them, while you write one. |
| `--test <stepfile>` | Checks its gates offline against recorded cases. |
| `--record-cases <dir>` | Records those cases from a real run. |
| `--auth <stepfile> <credential>` | Signs in to an MCP server that uses MCP authorization and prints the variables to set ([details](docs/connect.md#mcp-servers-that-use-mcp-authorization)). |
| `--verify <ledger>` | Checks a run's ledger for edits. |
<p align="right">(<a href="#readme-top">back to top</a>)</p>
## Catalog
[awesome-stepfiles/](awesome-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 [awesome-stepfiles/README.md](awesome-stepfiles/README.md), or [suggest an idea](https://github.com/Chaarangan/stepgate/issues/new?template=stepfile_idea.yml).
<p align="right">(<a href="#readme-top">back to top</a>)</p>
## Documentation
| Document | What it covers |
|---|---|
| [docs/stepfile.md](docs/stepfile.md) | How to write a stepfile: fields, tools, credentials, steps and gates. |
| [docs/connect.md](docs/connect.md) | Connecting Claude Code, Claude Desktop and other MCP clients. |
| [docs/how-it-works.md](docs/how-it-works.md) | What Stepgate does during a run, its limits, errors and ledger. |
| [server/schema/stepfile.schema.json](server/schema/stepfile.schema.json) | The JSON Schema for stepfiles. |
| [CONTEXT.md](CONTEXT.md) | The project's vocabulary. |
| [Releases](https://github.com/Chaarangan/stepgate/releases) | What changed in each version. |
<p align="right">(<a href="#readme-top">back to top</a>)</p>
## Contributing
Bug reports, new stepfiles for the catalog and pull requests are all welcome. The [open issues](https://github.com/Chaarangan/stepgate/issues) list proposed features and known bugs, and those labelled [good first issue](https://github.com/Chaarangan/stepgate/labels/good%20first%20issue) are small enough for a first pull request. Adding a stepfile needs no server knowledge: follow [awesome-stepfiles/README.md](awesome-stepfiles/README.md). For changes to the server or the format, see [CONTRIBUTING.md](CONTRIBUTING.md).
To report a vulnerability, follow [SECURITY.md](SECURITY.md). Everyone taking part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
### Contributors
<a href="https://github.com/Chaarangan/stepgate/graphs/contributors">
<img src="https://contrib.rocks/image?repo=Chaarangan/stepgate" alt="Contributors to Stepgate" />
</a>
<p align="right">(<a href="#readme-top">back to top</a>)</p>
## License
Distributed under the [Apache License 2.0](LICENSE).
<p align="right">(<a href="#readme-top">back to top</a>)</p>
## Contact
[![GitHub][github-shield]][github-url]
<p align="right">(<a href="#readme-top">back to top</a>)</p>
## Acknowledgments
* [Model Context Protocol](https://modelcontextprotocol.io/)
* [JSON Schema](https://json-schema.org/) and [Ajv](https://ajv.js.org/)
* [JSONLogic](https://jsonlogic.com/)
* [Best-README-Template](https://github.com/othneildrew/Best-README-Template)
* [contrib.rocks](https://contrib.rocks/)
<p align="right">(<a href="#readme-top">back to top</a>)</p>
[ci-shield]: https://github.com/Chaarangan/stepgate/actions/workflows/ci.yml/badge.svg
[ci-url]: https://github.com/Chaarangan/stepgate/actions/workflows/ci.yml
[npm-shield]: https://img.shields.io/npm/v/stepgate.svg
[npm-url]: https://www.npmjs.com/package/stepgate
[stars-shield]: https://img.shields.io/github/stars/Chaarangan/stepgate.svg
[stars-url]: https://github.com/Chaarangan/stepgate/stargazers
[issues-shield]: https://img.shields.io/github/issues/Chaarangan/stepgate.svg
[issues-url]: https://github.com/Chaarangan/stepgate/issues
[license-shield]: https://img.shields.io/badge/license-Apache--2.0-blue.svg
[license-url]: LICENSE
[typescript-shield]: https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white
[typescript-url]: https://www.typescriptlang.org/
[node-shield]: https://img.shields.io/badge/Node.js-5FA04E?style=for-the-badge&logo=nodedotjs&logoColor=white
[node-url]: https://nodejs.org/
[mcp-shield]: https://img.shields.io/badge/MCP-000000?style=for-the-badge&logo=modelcontextprotocol&logoColor=white
[mcp-url]: https://modelcontextprotocol.io/
[jsonschema-shield]: https://img.shields.io/badge/JSON%20Schema-000000?style=for-the-badge&logo=json&logoColor=white
[jsonschema-url]: https://json-schema.org/
[jsonlogic-shield]: https://img.shields.io/badge/JSONLogic-555555?style=for-the-badge
[jsonlogic-url]: https://jsonlogic.com/
[github-shield]: https://img.shields.io/badge/Chaarangan-181717?style=for-the-badge&logo=github&logoColor=white
[github-url]: https://github.com/Chaarangan
Connection Info
You Might Also Like
No recommendations available