jaimenbell/rails-mcp

A self-hosted, caller-configured **default-deny action registry** +
append-only **spend ledger** + CLI-only **sign-off audit trail**, exposed
as MCP tools. Different category from this author's other six MCP servers
(mcp-factory, rag-mcp, bus-mcp, desktop-mcp, github-mcp, discord-mcp) --
those are devtools ("connect an agent to X"); this one is **governance and
safety**: "stop an agent from doing something irreversible without a human
noticing."
Ported and generalized from a live internal registry (shared/rails/,
31 tests, running against a real multi-bot fleet since 2026-07-06) --
this pattern shipped internally before it shipped publicly.
What this is / is not
**Is:**
- A schema + pure logic for classifying action_type strings as
unconditionally **GATED** (default-deny), registered or not.
- A place to **register** what you know about an action-type's current
enforcement (enforcement_layer, enforcement_pointer, ceremony) --
informational, never permissive.
- An append-only **spend-intent ledger** + rolling-window budget check.
- An append-only **human sign-off ledger**, recording who blessed the
registry's current hash and when.
**Is NOT:**
- **Not an enforcer.** classify_action returning GATED does not block
anything by itself. You still wire it into your own PreToolUse hook,
permission deny-list, or CI gate -- rails-mcp gives you the schema and
the audit trail, not the interceptor. record_spend_intent records
intent to spend; it never calls a vendor, a paid API, or a broker, and
nothing here stops an over-budget spend from happening.
- **Not pre-loaded with any action-type data.** Every adopter supplies
their own registry (a YAML/JSON config file, or a plain dict). No
fleet's specific action-types ship with this package.
- **Not multi-tenant.** The sign-off ledger assumes one human operator
string per registry; fine for v1, a known limitation for later.
The one invariant that is never configurable
classify_action(action_type) **always** returns "GATED" -- registered
or not, whatever config was loaded, no argument or config field can change
it. This is the whole product. A config-driven fail-open knob would defeat
the entire pitch, so classify() (rails_mcp/registry.py) takes only an
action_type argument: there is no parameter through which a caller could
ever make it return anything permissive. is_action_registered answers a
separate, purely informational question -- "do I know something about this
action-type's enforcement?" -- and never feeds back into the GATED verdict.
Quickstart (60 seconds)
Add to your Claude Desktop/Code MCP config:
No console script on PATH? Fall back to "command": "python", "args": ["-m", "rails_mcp"].
By default the registry loads **empty** (honest-empty, not fail-open --
classify_action is still unconditionally GATED for everything). Point
it at your own action-type config:
See examples/rails.config.example.yaml (or .example.json) for the
config shape.
Tools
All six are **read-mostly** -- none of them can write to the sign-off
ledger.
| Tool | Purpose |
|---|---|
| classify_action(action_type) | Default-deny verdict: always "GATED". Implemented in rails_mcp/registry.py::classify, tested in tests/test_registry.py + tests/test_server.py. |
| is_action_registered(action_type) | Whether the loaded registry has an entry, plus enforcement_layer/enforcement_pointer/ceremony when present. rails_mcp/routes.py::is_action_registered, tested in tests/test_routes.py. |
| get_rails_hash() | 12-hex sha256 digest of the loaded registry + entry count -- the value a human sign-off records. rails_mcp/registry.py::rails_hash, tested in tests/test_registry.py. |
| get_signoff_state() | Current active human sign-off, or null. Read-only. rails_mcp/registry.py::load_signoff_state, tested in tests/test_registry.py + tests/test_routes.py. |
| record_spend_intent(amount_usd, vendor, purpose, actor) | Append one spend-intent record. Never calls a vendor or paid API. rails_mcp/spend_ledger.py::record_spend_intent, tested in tests/test_spend_ledger.py. |