AgenticRail Gate - sequence enforcement and verifiable audit receipts for AI age
Deterministic runtime enforcement of step order for AI agents: ALLOW/DENY before a step runs.
Open source Repository Open in the app JSON README (API)
About
Deterministic runtime enforcement of step order for AI agents: ALLOW/DENY before a step runs.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- nz.agenticrail
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.2.0
- Last push
- 2026-08-26T22:19:26Z
- Repository state
- ativo
- Language
- JavaScript
- Added
- 2026-08-29 04:01:50
- Updated
- 2026-08-29 04:01:50
- Origin id
nz.agenticrail/gate
README
# agenticrail-mcp
A **Model Context Protocol** server that exposes the live [AgenticRail](https://agenticrail.nz) enforcement gate to any MCP client as two tools.
AgenticRail is a deterministic enforcement layer for AI agents: it holds an agent to its declared step order, refuses replays and skipped steps, and seals each completed sequence with a signed receipt. This server is the MCP adapter in front of it.
**Endpoint:** `https://mcp.agenticrail.nz/` (Streamable HTTP, stateless)
**Protocol:** `2026-07-28` — the revision that retired the `initialize` exchange and `Mcp-Session-Id`. This server was built stateless with neither, so it needed no migration. `initialize` is still answered for older clients.
**Registry:** `nz.agenticrail/gate` on the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=agenticrail)
## Tools
| Tool | What it does | Calls |
|------|--------------|-------|
| `evaluate_step` | ALLOW/DENY a single agent step **before** it runs; seals a signed receipt | `POST https://api.agenticrail.nz/v1/evaluate` |
| `verify_receipt` | Fetch a sequence's verification report; confirm the receipt chain is intact | `POST https://report.agenticrail.nz/report` |
Call `evaluate_step` before running each step of a sequence, and do not run a step the gate DENYs.
### A DENY tells you how to fix it
Every refusal carries its own remedy in the response envelope — unsigned, DENY-only, because it describes the sequence's state now rather than the decision that was made:
| refusal | what comes back |
|---|---|
| `ACTION_NOT_ALLOWED` | `allowed_action_types` — exactly what this step would have accepted |
| `SEQUENCE_VIOLATION` | `next_expected_step` — the step the sequence is waiting for |
| `STEP_ORDER_MISMATCH` | `locked_step_order` — the order this sequence was locked to on its first call |
| `UNKNOWN_STEP` | `expected_step_order` + `step_order_source` (`caller` or `msmd_spine`) |
`action_type` is an **enum of eight values**, and each step accepts only a subset — a compliant client cannot construct an invalid one. **`step_order` is locked on the first call and needs at least one entry**; omitting it selects the built-in MSMD spine rather than clearing the lock, so to change the plan, start a new `sequence_id`.
## Connect
```bash
# zero config — uses the public demo key
claude mcp add --transport http agenticrail https://mcp.agenticrail.nz/
# with your own key
claude mcp add --transport http agenticrail https://mcp.agenticrail.nz/ \
--header "Authorization: Bearer <your-agenticrail-key>"
```
Any Streamable-HTTP MCP client works — point it at the URL.
## Try it without installing anything
```bash
BASE=https://mcp.agenticrail.nz/
curl -s -X POST "$BASE" -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq .
# ⚠️ Use a sequence_id nobody else will pick. On the shared demo key the id is
# GLOBAL and sealing is PERMANENT — a fixed one in an example works once for one
# person on earth and returns SEALED_SEQUENCE for everyone after.
SEQ="mcp-smoke-$(date +%s)-$RANDOM"
curl -s -X POST "$BASE" -H 'content-type: application/json' \
-d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{
\"name\":\"evaluate_step\",
\"arguments\":{\"sequence_id\":\"$SEQ\",\"step\":\"intake\",
\"action_type\":\"CHECK_STATE\"}}}" | jq .
```
With no `Authorization` header the public demo key is used and your `sequence_id` comes back rewritten to **`demo-mcp-<your id>`** — `demo-` marks the public lane, `mcp-` marks it as anonymous MCP traffic. **Use the id returned in the response from then on; the one you sent will not resolve.** This is intended, not a leak.
**A `demo-` sequence's report needs no key to read, so treat anything you send on it as public.**
## Design — read before changing
- **Protocol adapter only.** This worker holds **no internal secrets** and has no privileged path to the enforcement core. It calls the same **public API** an external caller uses, so the tool logic is decoupled from AgenticRail's internals *and* from the MCP transport version.
- **Service bindings, not fetch.** `mcp.agenticrail.nz` is on the same zone as `api.` and `report.`, so a plain `fetch()` would be a same-zone loopback (Cloudflare error 1002). The bindings hit the identical public handlers — they are not an internal bypass.
- **Stateless Streamable HTTP.** No `Mcp-Session-Id` is issued or required; every POST is self-contained. The transport shell is `handleRpc` + the `fetch` handler — the only part a spec revision touches. The value-bearing calls (`callEvaluate` / `callVerify`) are plain HTTPS and don't change.
- **`GET /` serves the discovery card; every other GET path 404s.** `POST` is left permissive on purpose so a client that appends a path to the endpoint URL still works.
- **A 404 on `/.well-known/oauth-*` is correct** — it is how an MCP server says *no auth required*. `agent.json`, `agent-card.json`, `x402` and `ai-plugin.json` are protocols this server does not implement; answering them would be a claim.
## Deploy
```bash
npx wrangler deploy
```
## Links
- Docs — https://agenticrail.nz/docs/
- Verify a sequence yourself — https://report.agenticrail.nz/report
- OpenAPI — https://agenticrail.nz/openapi.json
- Enforcement spec — https://agenticrail.nz/spec/
---
Operated by TUARA KURI LIMITED (NZBN 9429053582867), Hokianga, Aotearoa New Zealand.