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)

pip install rails-mcp

Add to your Claude Desktop/Code MCP config:

{
  "mcpServers": {
    "rails-mcp": {
      "command": "rails-mcp"
    }
  }
}

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:

{
  "mcpServers": {
    "rails-mcp": {
      "command": "rails-mcp",
      "env": { "RAILS_MCP_CONFIG_PATH": "C:\\path\\to\\rails.config.yaml" }
    }
  }
}

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.

The CLI-only sign-off boundary -- and why it exists

append_signoff -- the function that records a human blessing the registry's current hash -- is deliberately not an MCP tool, and never will be. It is exposed only as a CLI command a human runs by hand:

rails-mcp sign --operator "jaime" --note "reviewed 2026-07-16 config"

Why: the boundary exists to prevent an agent holding only this server's MCP tool connection from self-approving an irreversible action. If append_signoff were reachable as an MCP tool, any agent holding this server's connection could sign its own registry -- silently defeating the one thing the boundary exists to enforce. This mirrors the internal design rule the original shared/rails/ implementation was built around: the lane that builds the auditor never signs the registry it ships. An auditor that can also sign isn't an auditor.

What this boundary does not prove: the sign-off ledger has no cryptographic tamper-evidence and no binding to a real human identity -- its integrity rests entirely on filesystem ACLs and the self-hosted deployment model, not on cryptography. An agent (or anyone) with shell or file-write access to the ledger's path can run rails-mcp sign itself, or hand-append a forged {"type": "signoff", ...} JSONL line straight into the file -- the ledger has no way to tell that apart from a real CLI invocation. The MCP-only boundary stops the narrower case of an agent that has only this server's MCP tool connection; it is not proof that a human reviewed anything, and shouldn't be read as one.

This boundary is enforced structurally, not just by convention:

• rails_mcp/server.py and rails_mcp/routes.py never import or call append_signoff, anywhere -- proven by an AST-based check (not a naive string grep, which would false-positive on this very explanation appearing in their docstrings) in tests/test_server.py::test_append_signoff_unreachable_via_any_mcp_tool.
• The registered MCP tool set is exactly the 6 read-mostly tools above -- no sign/append_signoff/revoke_signoff tool exists, checked in tests/test_server.py::test_all_six_rails_tools_registered.
• A behavioral test drives every registered tool and confirms the sign-off ledger file is never created (test_no_registered_tool_can_create_a_signoff_record).
• run_server.py (the entrypoint ~/.claude.json invokes) imports only rails_mcp.server, never rails_mcp.cli -- so even the process that serves MCP tools has no code path to the sign subcommand.

Env vars

Config file shape

actions:
  deploy_prod:
    enforcement_layer: "L1"
    enforcement_pointer: "CI gate requires a passing e2e suite + a manual approve step"
    ceremony: "operator hand"

Or the more compact 3-element form (matches the internal registry's native shape):

actions:
  deploy_prod: ["L1", "CI gate requires a passing e2e suite + a manual approve step", "operator hand"]

JSON works identically ({"actions": {"deploy_prod": [...]}}). See examples/ for full examples of both.

enforcement_layer should be honest, not aspirational -- "prose" (no structural rail exists yet, just a doc) is a legitimate, correct value. Rounding a "prose" entry up to "L1" because it feels better defeats the entire point of an honest registry.

Testing

.venv/Scripts/python.exe -m pytest -q

CI (.github/workflows/ci.yml) runs this suite on every push/PR and fails the build if the Tests badge above drifts from what the suite actually reports -- see scripts/check_readme_counts.py.

106 tests, all hermetic (every ledger/config path goes through tmp_path + an autouse env-isolation fixture in tests/conftest.py; nothing touches a real ./rails_data/). No network, no live-smoke gate needed -- this server has no external API to fake.