Authentication says who's at the door. Reeve decides what they can touch, and remembers what they touched.
A Ruby gem that makes it safe for a Rails application to expose MCP tools to AI agents: declarative per-record authorization, an append-only audit ledger, and a testing kit that proves both hold.
Status: 0.10.0. Read the known limitations in CHANGELOG.md before adopting it — particularly the one about a transaction wrapped around an invocation, if your application wraps requests in one.
A reeve is an official who acts with delegated authority on behalf of someone else — the root of "sheriff" (shire-reeve). That delegation is exactly what this gem governs: an agent acting for a human, allowed to reach only what that human may reach.
Developed under the working name mcp-guardrails.
The Ruby MCP server stack — the official mcp
gem, fast-mcp, and
ActionMCP — is healthy and consolidating. All three
authenticate the connection. None of them scope what an authenticated agent may see per
person, none produce a compliance-grade audit trail, and none ship a way to prove either
in CI.
That's the gap Reeve fills. It's an extension layer, not a competitor — it rides all three.
bundle add reeve
bin/rails generate reeve:install
bin/rails db:migrate1. Say who the agent is acting for. This is the only thing Reeve cannot work out for itself, and the generated initializer leaves it as a TODO:
# config/initializers/reeve.rb
Reeve.configure do |config|
config.principal_resolver = lambda do |context|
ApiToken.find_by(token: context.metadata.dig(:headers, "Authorization"))&.user
end
config.unguarded_tools = :deny # :deny | :allow_with_warning
config.redact_arguments = %i[password token ssn]
endUntil that resolver is set, every guarded call denies with no_principal. That is the
intended behaviour: the library is safe before it is configured. The initializer also
derives the key that chains the audit ledger from secret_key_base, so that works in
every environment with nothing to set up — see Tamper-evident, within stated
limits.
2. Guard a tool.
class InvoiceSearchTool < FastMcp::Tool
guard_with InvoicePolicy # the only line you add
redact :customer_ssn
def call(query:)
Invoice.where("number LIKE ?", "%#{query}%")
end
end3. Prove it in CI.
RSpec.describe InvoiceSearchTool do
it { is_expected.to deny_access_for(stranger).with(query: "AC") }
it { is_expected.to audit_every_call }
endThree things now hold, and each is a test you can run rather than a claim you have to trust.
A tool returns only the records its principal may see. No principal, no guard_with, or a
policy that raises means no records — never a silent pass. A single record outside the
principal's scope is refused in a way that does not reveal whether it exists:
Reeve.invoke(tool: InvoiceShowTool, arguments: { id: 41 }, principal: alice)
# => Reeve::DeniedError: reeve denied invoice_show_tool for principal 1:
# out_of_scope_record (the requested record is not within this principal's scope)The error names the rule and never names the record. One caveat worth knowing: fetching
from the unscoped model still lets a caller tell "someone else's" (a denial) from "no such
record" (nil). If that distinction matters, fetch through scoped, where both answers
are nil:
def call(id:)
scoped(Invoice).find_by(id: id)
endAnything that is not a record — a count, a sum, a summary — is safe only when it was
computed from scoped, because then the tool never held unscoped data:
class OverdueTotalTool
include Reeve::Guard
guard_with InvoicePolicy
def call
scoped(Invoice).where(overdue: true).sum(:cents) # safe by construction
end
endReaching for Invoice.sum(:cents) there is denied with unscoped_derived_result. The
guarantee is structural, not a matter of remembering.
A denial means nothing happened. Authorization runs before the tool, but with the model class as its subject — for an index-style check there is no record yet — so the per-record answer only arrives once the tool has returned something to scope. A write tool sits between those two points:
def call(id:, number:)
invoice = Invoice.find(id) # unscoped fetch
invoice.update!(number: number) # ...then a write
invoice
endThe tool body runs in a transaction, and a scope denial rolls it back. Someone else's
record is refused and unchanged, and the ledger's deny is a true statement about the
database. A transaction the host opened around the invocation is untouched — the rollback
reaches the tool's work and stops there.
What a rollback cannot reach is anything that was never in the transaction. A tool that sends an email, calls a webhook or writes a file before it knows whether it is allowed to must ask first:
def call(id:, to:)
invoice = authorize!(Invoice.find(id)) # raises DeniedError if the policy says no
InvoiceMailer.reminder(invoice, to).deliver_now
invoice
endauthorize! asks the declared policy about one record and returns it, so it reads inline.
The denial carries the policy's own rule into the ledger, and names no record — a refusal
and a record that does not exist have to read the same.
One append-only row per invocation, allowed or denied, naming the agent, the principal, the arguments (post-redaction), what came back, and the rule that decided:
Reeve::Audit::Query
.for_principal(user)
.for_agent("claude-desktop")
.between(1.week.ago, Time.current)
.pluck(:occurred_at, :tool_name, :outcome, :rule, :record_type, :record_ids)A call whose tool raised is still recorded — that trace is the one most worth having. A
call that cannot be recorded fails, unless the host has explicitly opted into
audit_failure_mode = :warn.
If your application wraps invocations in a transaction — a controller that opens one per request, a job runner — a rollback takes the ledger row with it, and exactly the calls worth auditing are the ones that rolled back. Write on a connection the rollback cannot reach:
config.audit_recorder = Reeve::Audit::IsolatedRecorderIt needs a database with concurrent writers and refuses on SQLite, where an open
transaction holds the write lock; IsolatedRecorder.available? lets you branch if you
develop on one and deploy on the other. The default recorder warns when it detects the
case rather than failing silently.
Every row Reeve writes is linked to the one before it by a keyed digest (HMAC-SHA256), with a key the database does not hold. Someone who can write to the ledger table but does not hold the key can still change it, but the change shows when the chain is checked:
bin/rails reeve:verify_ledgerreeve ledger: INTACT — sequences 1–48,211 verified (head at start: 48,211); 5,000 earlier entries not covered (5,000 when the chain started); not anchored
It exits 0 when the chain is intact, 1 when it is broken, and 2 when it could not
verify (no chain, no key, or rows signed by a key it does not hold). Run it on a schedule
and alert on anything but 0. LIMIT= caps the breaks it lists, never the totals;
FORMAT=json writes every break. The same answer from Ruby, or with an auditor's own copy
of the key:
result = Reeve::Audit::Chain.verify
result.status # => :intact, :broken, :unverifiable or :no_chain
result.covered # => 1..48211
puts result # the report above, with every break listed under itIn CI the compliance suite you already run includes LedgerChain, in both frameworks:
it writes entries of its own and fails on a broken chain, a missing key, or entries that
were not chained. "Not anchored" on the summary line is explained under Anchoring the
chain below.
The key. The generated initializer derives it from secret_key_base:
config.ledger_key = Rails.application.key_generator.generate_key("reeve audit ledger", 32)Rotating secret_key_base therefore rotates the ledger key. Keep the old one, or the
entries it signed become unverifiable — reported as such, never as tampered:
config.retired_ledger_keys = [old_key] # verify with these; new epochs never open with themRotating the key. Every key that signs the ledger opens a numbered key epoch, and every
entry records its epoch inside its digest. To rotate: set the new key as ledger_key and the
old one in retired_ledger_keys (in that order), deploy, then run
bin/rails reeve:rotate_ledger_keyIt reports ROTATED or CURRENT (exit 0), or REFUSED (exit 1, nothing written) — for
instance when the current epoch's key is not configured where it runs, since that epoch's
entries would become unverifiable there. Writes never wait for it: the first write with the
new key opens its epoch, and servers still on the old key during the deploy keep writing
under theirs. From Ruby:
rotation = Reeve::Audit::Chain.rotate_key!
rotation.status # => :rotated, :current or :refused
rotation.epoch # => 1Verification then lists each epoch under its summary line, with the key fingerprint, where it begins, and whether it verified. The CHANGELOG has the full procedure.
Anchoring the chain. The chain's own records live in the same database as the entries, so someone who deletes the newest entries and rewinds the head to match, or deletes the whole ledger, leaves nothing behind that verification can see. A checkpoint is a second witness: one signed line saying how far the chain reached (its genesis, its head, its latest key epoch), kept where the database's users cannot change it. It holds digests and counts only, never entry content or a key.
Point an anchor at that storage. The line goes at the bottom of
config/initializers/reeve.rb, after require "reeve/audit" (which defines FileAnchor),
outside the Reeve.configure block, hence Reeve.config:
require "reeve/audit"
Reeve.config.ledger_anchor =
Reeve::Audit::FileAnchor.new("/mnt/ledger-anchor/#{Rails.env}.checkpoints")Use one anchor per environment, on storage outside the database host, such as a mount backed
by an object-locked bucket; a file next to the database protects nothing. The hosts that make
checkpoints need to write the file (it is created on the first one), and the hosts that verify
need to read it. Any object with publish(line) and checkpoints works in its place.
Then make a checkpoint on a schedule, from one host (hourly, say), and keep verifying as
before. Alert on anything but 0 from either task. reeve:checkpoint_ledger exits 1 when
it refused (no key, or no chain until the first guarded call) or the anchor failed, and still
prints the line so it can be stored by hand. Two runs at once are safe.
bin/rails reeve:checkpoint_ledger # exit 0 made and published
bin/rails reeve:verify_ledger # checks the ledger against every checkpointreeve ledger: INTACT — sequences 1–48,211 verified (head at start: 48,211); 5,000 earlier entries not covered (5,000 when the chain started); anchored at #48,000 (checkpoint 2026-10-25 14:00 UTC), 211 entries after it
Every checkpoint is checked: a ledger that no longer reaches one, holds another entry where it
saw one, or lost an epoch record it named, is BROKEN (exit 1), and so is an emptied ledger,
which without a checkpoint reads only as "no chain". The newest entries deleted with the head
rewound read like this:
reeve ledger: BROKEN — 1 break in sequences 1–46,211; 5,000 earlier entries not covered (5,000 when the chain started); anchored at #44,000 (checkpoint 2026-10-25 13:00 UTC), 2,211 entries after it
totals: checkpoint_not_reached 1
checkpoint #48,000 checkpoint_not_reached the head is at 46,211; entries the checkpoint saw were removed
What it does not cover: entries written after the latest checkpoint can still be removed
without trace. "211 entries after it" counts the entries still there past the checkpoint; it
cannot see ones that were deleted, so how often you checkpoint is the size of that window.
reeve:rotate_ledger_key makes a checkpoint itself after opening an epoch. Writes never touch
the anchor.
Restores and resets. Restoring a backup older than a checkpoint reads as BROKEN, truthfully:
the restored ledger lost entries that checkpoint saw. Resetting a database on purpose (a
staging rebuild) is the same, so start a new anchor file for the new ledger: change the path
(staging-2026-10-25.checkpoints, say), keep the old file as the record of the old ledger, and
make a checkpoint. Until then the run reads "not anchored". CHECKPOINTS= (empty) verifies
without any checkpoint, for a one-off check, never as the fix.
Other sources, large ledgers. CHECKPOINTS=path verifies against a file of checkpoint lines
instead of the anchor, say an auditor's copy. FROM=latest walks only what came after the
newest checkpoint: it first checks that checkpoint (its signature, the genesis and epoch it
names, and that its entry still has the digest it saw), then verifies every entry after it.
Entries before it are not re-verified by that run, and the summary says how many; keep a full
run on a slower schedule. With no checkpoint to start from it exits 2. From Ruby:
Reeve::Audit::Chain.checkpoint!.checkpoint.to_line # => "{\"epoch\":1,…}"
Reeve::Audit::Chain.verify(checkpoints: lines).anchored_at # the highest checkpoint that heldIn CI. The compliance suite's LedgerChain check never reads the anchor unless told to: a
test database is emptied between runs, and old checkpoints name ledgers that are gone. To
prove the anchor works, point the test environment's anchor at a scratch file and turn on
compliance_anchored, in the initializer after the anchor line above. The check then makes a checkpoint, reads it back through the anchor,
and verifies against that one alone. With no anchor configured, it fails and names the
setting.
if Rails.env.test?
Reeve.config.ledger_anchor =
Reeve::Audit::FileAnchor.new(Rails.root.join("tmp/ledger.checkpoints"))
Reeve.config.compliance_anchored = true
endOutside the suite, the same check runs on its own:
Reeve::Checks::LedgerChain.new(anchored: true).call.
Purging old entries. The ledger grows until you purge it. Deleting rows by hand breaks
the chain and is reported as tampering, so reeve purges for you: the oldest entries, up to a
checkpoint your anchor holds, after verifying the whole ledger INTACT, leaving a signed
retention record so the rest still verifies and the purge reads as a purge. It also removes
rows written before the chain began, and nothing else. It stops at a checkpoint, so with
OLDER_THAN=365d a few entries just over a year old can remain until the next run.
Setting it up, once. Run bin/rails generate reeve:upgrade && bin/rails db:migrate (it adds
reeve_audit_retentions), then create a database role only the purge uses; the application's
role never gains DELETE. On PostgreSQL (the migration's header shows the same grants):
CREATE ROLE reeve_retention LOGIN PASSWORD '…';
GRANT SELECT ON reeve_audit_entries, reeve_audit_chains, reeve_audit_chain_epochs,
reeve_audit_retentions TO reeve_retention;
GRANT DELETE ON reeve_audit_entries TO reeve_retention;
GRANT INSERT ON reeve_audit_retentions TO reeve_retention;
GRANT USAGE ON SEQUENCE reeve_audit_retentions_id_seq TO reeve_retention;
GRANT SELECT ON reeve_audit_retentions TO app_role; -- the application only reads itAdd the role to config/database.yml as a second database entry pointing at the same
database, and a class that connects through it:
production:
primary:
<<: *default
database: app_production
ledger_retention:
<<: *default
database: app_production # the same database
username: reeve_retention
password: <%= ENV["REEVE_RETENTION_PASSWORD"] %>
database_tasks: false # never migrated through this entry# app/models/ledger_retention_record.rb
class LedgerRetentionRecord < ActiveRecord::Base
self.abstract_class = true
connects_to database: { writing: :ledger_retention }
end
# config/initializers/reeve.rb, after require "reeve/audit"
Reeve.config.ledger_retention_connection = LedgerRetentionRecordThe purge refuses a connection to another database, or one that logs in as the application's own user. On SQLite, which has no roles, it can only warn. The task needs the ledger key, as every chain task does.
Running it. Monthly, from one host, a dry run first (no CONFIRM), then the purge. The
archive path must be new each run: an existing archive is never overwritten.
bin/rails reeve:purge_ledger OLDER_THAN=365d ARCHIVE=/mnt/archive/ledger-2026-10.jsonl # dry run
bin/rails reeve:purge_ledger OLDER_THAN=365d ARCHIVE=/mnt/archive/ledger-2026-10.jsonl CONFIRM=1reeve ledger purge: WOULD PURGE — sequences 1–6,000 through checkpoint #6,000 (2025-10-01 14:00 UTC): 6,000 chained entries and 5,000 pre-chain rows; archive to /mnt/archive/ledger-2026-10.jsonl; run again with CONFIRM=1
In crontab, escape the date's %: ledger-$(date +\%Y-\%m).jsonl. THROUGH=6000 names a
checkpoint's sequence instead of an age. Exactly one of ARCHIVE=path and NO_ARCHIVE=1 is
required; with neither the task refuses, with both it raises. Exit 0 covers a dry run, a
purge, and nothing old enough (the first line says which: WOULD PURGE, PURGED, NOTHING TO PURGE); exit 1 is a refusal, which removes nothing and names the fix:
| Refusal says | Fix |
|---|---|
| no anchor configured | set config.ledger_anchor and schedule checkpoints (above) |
| no retention connection / another database / the application's own database user | config.ledger_retention_connection and the role above |
| the ledger does not verify intact | read bin/rails reeve:verify_ledger; nothing is purged while anything is broken or unverifiable |
| no checkpoint the anchor holds is at that sequence | use one of the two it names, or OLDER_THAN |
| the archive … already exists, or cannot be written | a new path, in a directory the task can write |
Any other failure (a lost connection, a full disk) raises, exit 1 from Rake, like any task.
If it stops midway. The archive is written in full and the retention record committed
before any row is deleted. If the host dies during the deletes, verification reads INTACT,
exit 0, with ; 120 entries awaiting purge beside the purged range, which is not a break.
Run the purge again, the same command or any other: it first finishes the interrupted purge
(PURGED — … (resumed; 120 rows removed this run)), whatever boundary the new run names, and
skips the archive, which already exists. Run it once more to purge further.
The archive. Every purged row with every column, so the range can be checked without the ledger's rows:
bin/rails reeve:verify_archive ARCHIVE=/mnt/archive/ledger-2026-10.jsonl # reeve archive: INTACT — sequences 1–6,000 verified, …It runs inside the application (it needs the entries table's columns, from any database with
the schema, not the purged rows), with the keys that signed the archived rows configured as
ledger_key or retired_ledger_keys; the anchor is not needed. Each archive covers the range
its purge removed, named in its first line, so name files by the month they were made. Keep
archives where they cannot be changed, as you do the anchor. NO_ARCHIVE=1 deletes without
one, for data you must not keep; the record and the output then say no archive was written.
Keys. Keep every key you ever signed with. A purge removes entries, not epoch records or retention records, and verification still checks those under their own keys; archives need the keys of the rows they hold.
After a purge, every summary line names what was purged before its coverage; with
FORMAT=json, retention and awaiting_purge hold the same:
reeve ledger: INTACT — sequences 6,001–10,000 verified (head at start: 10,000); 1–6,000 purged (retention record 0, 2026-10-25); 0 earlier entries not covered (5,000 when the chain started, 5,000 purged); anchored at #10,000 (checkpoint 2026-10-25 14:00 UTC), 0 entries after it
Checkpoints older than the boundary read as purged. Deleting entries a retention record does
not cover, or editing or deleting a record, is BROKEN (retention_altered or missing), as
before.
A dedicated key decouples the two: config.ledger_key = Rails.application.credentials.reeve_ledger_key.
Keys must be at least 32 bytes and are only ever printed as 16-character fingerprints.
Without a key, every guarded call fails closed; under audit_failure_mode = :warn it is
recorded unchained instead, logged each time, and reported by verification.
Detected, provided the key has not leaked:
- a chained row whose recorded content was changed;
- a chained row removed from anywhere before the newest one;
- chained rows swapped, renumbered or moved, or a row inserted that Reeve did not write — including one numbered past the head;
- the newest rows removed while the chain record was left alone;
- the chain record removed while chained rows remain;
- an entry whose key id or key epoch was changed, or that names an epoch with no record, and an epoch record that was changed, or removed while entries name it (one forged under a key you do not hold reads as unverifiable, never intact);
- with checkpoints: any entry the latest checkpoint saw removed, even with the head rewound; the whole ledger deleted or replaced; an epoch record a checkpoint named, removed or changed; a checkpoint edited, or forged without a key you hold.
Not detected — stated plainly, because these are the limits of the guarantee:
- A leaked key. Anyone holding it can rewrite the chain from any point forward. By
default that is anyone holding
secret_key_base. Not past a checkpoint made before the leak, though: rewriting an entry it saw changes the digest it names. - The newest rows deleted by someone who also rewinds the chain record's head, unless a checkpoint saw them. Rows after the latest checkpoint stay exposed; the summary line counts them.
- The whole ledger deleted, chain record included, without a checkpoint. Reported as no chain, never as a pass, but indistinguishable from a ledger that was never chained. And checkpoints are only as safe as their store: one an attacker can delete protects nothing.
- Rows written before you upgraded. They are counted as "not covered" and are exactly as trustworthy as they were before. Likewise, entries without a key epoch — chained by 0.6.0, before or during the upgrade — are checked as 0.6.0 checked them: a rewritten key id on one of them reads as unverifiable, not as tampering.
- A key you no longer hold. Entries it signed cannot be checked, by anyone. Epochs make that visible and name the epoch; they do not undo it.
- What a purge removed. Without an archive, nobody can read it again; the retention record proves only that it existed, verified, and was removed on purpose. A row edited inside the range while the purge runs is not reported by the ledger, since it is being removed; the archive holds what was read.
And it prevents nothing: it detects a change after the fact. The GRANT INSERT, SELECT in
the generated migration is what prevents one. The chain record needs UPDATE as well,
which is why a role allowed to rewind it is limit 2.
What it costs. About half a millisecond per ledger write on SQLite and about one on
PostgreSQL. Every chained write locks the chain record, so writes serialize. Under the
default recorder inside a transaction your application opened, that lock is held until the
transaction ends, and every other guarded call waits behind it — up to the database's own
lock wait: indefinitely on PostgreSQL (lock_timeout is 0 by default), 50 seconds on MySQL
(innodb_lock_wait_timeout), and ActiveRecord's timeout on SQLite (5 seconds in a
generated database.yml). IsolatedRecorder holds it for the length of one insert. On
Rails 7.0 with SQLite, a thread waiting for SQLite's write lock holds Ruby's GVL
(sqlite3 1.x), so concurrent guarded calls in one process can fail closed after the busy
timeout. Rails 7.1+ or a server database avoids it.
Your own recorder. A recorder that writes to Reeve's table chains its rows through the same door the built-in ones use, or verification reports them as unchained:
Reeve::Audit::Chain.new(entry_class: Reeve::Audit::Entry).append!(row)Upgrading from 0.7.0: bin/rails generate reeve:upgrade && bin/rails db:migrate adds
reeve_audit_retentions; grant the application's role SELECT on it. Nothing is purged until
you run the task, and anchoring is opt-in. Every summary line now ends with its anchoring
(; not anchored until you set one up), so anything that matches the whole text line should
read FORMAT=json instead, whose existing keys are unchanged.
Upgrading from 0.6.0: bin/rails generate reeve:upgrade && bin/rails db:migrate before
the new code serves traffic, and grant INSERT, SELECT on reeve_audit_chain_epochs. The next guarded call opens epoch 0;
earlier entries are listed as "before epoch 0" and checked as before.
Upgrading from 0.5.0:
bin/rails generate reeve:upgrade
bin/rails db:migrateThen add the config.ledger_key line the generator prints. Existing rows are not touched;
the next guarded call starts the chain. Servers still on 0.5.0 during a rolling deploy keep
writing unchained rows, which are counted as not covered rather than reported as tampering.
All the logic lives in framework-neutral checks. RSpec and Minitest are thin front-ends over the same objects, emitting the same messages, so no guarantee is provable in one framework only.
# RSpec — require "reeve/rspec"
it { is_expected.to deny_access_for(stranger) }
it_behaves_like "a reeve-compliant server"# Minitest — require "reeve/minitest"
class ComplianceTest < ActiveSupport::TestCase
include Reeve::Testing::Assertions
include Reeve::Testing::ComplianceAssertions
def test_search_denies_a_stranger
assert_denies_access_for InvoiceSearchTool, stranger, query: "AC"
end
endA stock rails new application — Minitest, no RSpec — proves every guarantee without
adding a test framework. That is a spec in this repo, not an aspiration.
The checks are plain objects, so the same guarantees are assertable from a rake task, a CI script, or a boot-time assertion in staging:
require "reeve/testing"
report = Reeve::Checks.run_all(principals: [alice, bob])
abort report.to_s if report.failed? || report.nothing_checked?alice and bob are two fixture principals with disjoint records — that disjointness is
what makes a shared record identifier proof of a leak. passed? only means nothing failed,
so a run over no tools at all passes; nothing_checked? is what stops this gate when the
registry is empty, since a script has no pending test to show it.
The suite walks every tool that included Reeve::Guard, not only the ones that declared
a guard. A tool that forgot guard_with is the one worth finding, and it is absent from
the guard registry by definition — so a run that only inspected guarded tools reported
all-green on precisely the application that had a problem.
Mid-retrofit that means a red build, which is honest but unreadable if it stays red for weeks. Say what you have certified so far, and grow the list:
config.compliance_tools = -> { [InvoiceSearchTool, InvoiceShowTool] }Reeve can only see tools that reached it. If your MCP server dispatches tools Reeve has
never been told about — a custom controller with its own registry — declare the server's
real inventory (below), or the run certifies the
subset Reeve happens to know. Until you do, the suite says so: EndpointCoverage is
reported as skipped, never as passed.
As a Rails rake task:
# lib/tasks/reeve.rake
namespace :reeve do
desc "Fail the build if any guarded tool leaks or goes unaudited"
task compliance: :environment do
require "reeve/testing"
report = Reeve::Checks.run_all(principals: Reeve::Testing.compliance_principals)
abort report.to_s if report.failed? || report.nothing_checked?
puts report
end
endA failing run names the check, the tool, and the records that leaked:
reeve compliance: 13 checks, 12 passed, 1 failed
FAIL CrossPrincipalLeak
expected InvoiceSearchTool to return no records belonging to another principal, but it
returned 3 records to User#1 that also belong to User#2: Invoice#7, Invoice#8,
Invoice#9 (guard: InvoicePolicy, decision: allow via InvoicePolicy#index)
# config/initializers/reeve.rb
require "reeve/mcp"
Reeve.configure do |config|
# The user you passed to MCP::Server.new(server_context: { user: current_user }):
config.principal_resolver = ->(context) { context.request[:server_context]&.dig(:user) }
# Or the subject of the token the SDK's OAuth middleware verified:
# config.principal_resolver = ->(context) { User.find_by(id: context.request[:auth_info]&.subject) }
endclass InvoiceSearchTool < MCP::Tool
input_schema(properties: { query: { type: "string" } }, required: ["query"])
guard_with InvoicePolicy
def self.call(query:)
numbers = scoped(Invoice).where("number LIKE ?", "%#{query}%").pluck(:number)
MCP::Tool::Response.new([{ type: "text", text: numbers.join("\n") }])
end
endguard_with plus scoped. An SDK tool returns a finished response, not records, so
Reeve cannot narrow it per record as it narrows a fast-mcp tool's return value. It allows or
refuses the whole response: allowed only if the tool read through scoped(...) during the
call, otherwise refused unscoped_derived_result. authorize! checks a single record before
the tool uses it.
That check is one flag per call. A tool that calls scoped(Invoice) and also renders
Invoice.find(id) passes: Reeve proves the tool asked for scoped data, not that every value
it rendered came from it. Fetch any other record through authorize!.
Block tools are tools. server.define_tool builds a tool class like any other, so an
unguarded block tool is refused no_guard_declared. Guard it on the class the server holds:
server.define_tool(name: "list_invoices") do |server_context:|
MCP::Tool::Response.new([{ type: "text", text: scoped(Invoice).pluck(:number).join("\n") }])
end
server.tools["list_invoices"].guard_with InvoicePolicyEach block is a new class, and Reeve keeps every tool class it sees. If you build a server
per request, define block tools once at boot with MCP::Tool.define, guard them there, and
pass them in tools:.
What the client receives. Allowed: the tool's own response. Denied: a tool error
(isError: true) whose text names the tool, the principal and the rule, never a record; a
resolver that returns nil is a denial, no_principal. A tool that raises: the SDK's usual
internal error. Every one of these writes exactly one ledger row.
Request data is not recorded. The resolver reads context.request: the SDK's
server_context and auth_info. They can hold a user object or a token, so neither is
written to the ledger; the row records only the client's name and version. If you dispatch
through Reeve.invoke yourself, pass the same kind of thing as request:, and only what
you would want in an audit as metadata:.
Before deploying. Requiring reeve/mcp under :deny refuses every SDK tool without
guard_with, block tools included, on its next call. While adopting, set
config.unguarded_tools = :allow_with_warning: unguarded tools run, unscoped, and each call
logs a warning to config.logger and is recorded with guard: "none". The matchers and the
compliance suite take SDK tool classes as they are; no custom invoker is needed.
Supported: mcp 1.x (verified on 1.0.0 and 1.9.0), Ruby 3.0+, with or without Rails.
fast-mcp and the SDK cannot share a process: fast-mcp ships files at the paths the SDK loads
its classes from, and reeve/mcp raises Reeve::ConfigurationError if fast-mcp got there
first.
# config/initializers/reeve.rb
require "reeve/action_mcp"
Reeve.configure do |config|
# The user ActionMCP's gateway authenticated for this request:
config.principal_resolver = ->(_context) { ActionMCP::Current.user }
endclass InvoiceSearchTool < ApplicationMCPTool
property :query, type: "string", required: true
guard_with InvoicePolicy
def perform
scoped(Invoice).where("number LIKE ?", "%#{query}%").each do |invoice|
render(text: invoice.number)
end
end
endThe same rule as on the SDK: guard_with plus scoped. A tool renders as it goes, so
Reeve holds what it renders and releases it only if the call is allowed; a tool that read
nothing through scoped(...) is refused unscoped_derived_result and nothing it rendered
reaches the client. The check is one flag per call, with the same consequence as on the SDK:
fetch any record you did not get from scoped through authorize!.
What the client receives. Allowed: what the tool rendered. Denied: a tool error naming
the tool, the principal and the rule, never a record; no user is a denial, no_principal.
A tool that raises: ActionMCP's own error, unchanged. Each writes exactly one ledger row. A
call that request_input! interrupts is recorded tool_error and releases nothing.
Calls that write no row. A before_perform callback of yours that halts, or input
ActionMCP's schema refuses, stops the call before the tool runs, so there is nothing to
guard or record. The client gets ActionMCP's usual error for each.
Background tasks have no user. A task-augmented call runs in ActionMCP's
ToolExecutionJob, which does not set ActionMCP::Current.user. With the resolver above it
is refused no_principal and recorded. If your sessions carry the user, resolve it from
context.request[:session]. The session is request data: it reaches the resolver and is
never recorded; the row records only the client's name and version.
ApplicationMCPTool and any other class that calls abstract! is a base, not a tool: the
compliance suite does not ask whether it is guarded. Requiring reeve/action_mcp under
:deny refuses every unguarded ActionMCP tool, as on the SDK.
Supported: actionmcp 0.200 to 0.203 (verified on 0.200.0 and 0.203.0), which needs Rails
8.1 and Ruby 3.2+. The adapter reaches into ActionMCP's internals, so it refuses to load on a
version it was not verified against; each new ActionMCP minor needs a Reeve release.
The core needs neither. Reeve.invoke is the same envelope with the same guarantees:
require "reeve"
Reeve.invoke(
tool: InvoiceSearchTool,
arguments: { query: "AC" },
principal: current_user,
agent: { id: "claude-desktop" }
)Plenty of Rails apps expose /mcp from a controller they wrote themselves, with their own
tool registry and their own bearer-token authentication. There is no adapter to install
for that, and none is needed: Reeve.invoke is the adapter interface. An MCP integration
is a function from a JSON-RPC request to one Reeve.invoke call.
Keep the authentication you have. Reeve does not do connection auth (see What you have not gained) — the controller still decides whether the caller gets in the door, and Reeve decides what they may touch once inside.
Dispatch through the envelope. Map the JSON-RPC tool name to the class, then call:
# app/controllers/mcp_controller.rb
def call_tool
tool = McpServer.registry.fetch(params.dig(:params, :name))
records = Reeve.invoke(
tool: tool,
arguments: params.dig(:params, :arguments).to_h.symbolize_keys,
agent: { id: request.headers["X-MCP-Client"] || "unknown" },
metadata: { headers: request.headers.to_h.slice(*AUDITED_HEADERS) }
)
render json: { jsonrpc: "2.0", id: params[:id], result: serialize(records) }
rescue Reeve::DeniedError => e
render json: { jsonrpc: "2.0", id: params[:id],
error: { code: -32_003, message: e.message } }
endNote what is not passed: principal:. Omit it and the resolver in your initializer runs,
which is what you want when the controller has already set Current.user — one place
decides who the principal is, and the ledger records the same answer the guard used.
Passing principal: explicitly overrides the resolver for that call, which is useful in
tests and in scripts.
metadata: is transport detail, and it is recorded. It reaches the resolver as
context.metadata and is written to the ledger's metadata column, so it is what a
reviewer has to reconstruct which request a row came from. It goes through the same
redactor as the arguments, so Authorization and friends are replaced by name — but pass
the headers you would want in an audit rather than all of them.
Resolve the principal from whichever the controller established:
Reeve.configure do |config|
config.principal_resolver = lambda do |context|
Current.user || ApiToken.find_by(
token: context.metadata.dig(:headers, "Authorization").to_s.delete_prefix("Bearer ")
)&.user
end
endA resolver that returns nil — or raises — denies with no_principal and still writes a
row. There is no configuration in which an unidentified caller reaches a tool.
Adopt one tool at a time. A registry of thirty tools does not need thirty policies before any of this is worth turning on:
config.unguarded_tools = :allow_with_warning # migratingTools with guard_with are authorized and scoped normally. Tools without one still run —
unscoped, which is the entire point of the warning — and are recorded with guard: "none"
and rule unguarded_tool, so the ledger itself is your worklist:
Reeve::Audit::Entry.where(guard: "none").distinct.pluck(:tool_name)Flip to :deny when that comes back empty, and the mode stops being reachable by accident.
The compliance checks work here too, and they take an invoke: argument precisely so they
run against your dispatcher rather than a synthetic call:
Reeve::Checks.run_all(
principals: [alice, bob],
invoke: ->(tool:, principal:, arguments:) { McpServer.dispatch(tool, principal, arguments) }
)That is the whole integration: one call site, your auth untouched, and the same three guarantees the fast-mcp adapter gets.
Reeve protects the tools routed through it, and only those. A server that registers tools
as names and handler blocks can send some through Reeve.invoke and run the rest directly
— and the direct ones are not unguarded, they are invisible: no denial, no scope, no ledger
row, and nothing that says so. Deny-by-default cannot deny a call it never sees.
Reeve::Inventory makes the server's own list of names the thing that gets checked:
# config/initializers/reeve.rb
McpInventory = Reeve::Inventory.new(
registered: -> { McpServer.tool_names },
routed: -> { { "search_invoices" => InvoiceSearchTool, "get_invoice" => InvoiceShowTool } },
exemptions: { "healthcheck" => { reason: "returns no application data" } }
)
Reeve.configure { |config| config.inventory = McpInventory }Each part takes a value or a callable. Callables are read when asked, so the initializer neither autoloads application constants nor runs before the server has registered its tools.
reeve inventory: 4 registered
2 protected and guarded
0 routed through reeve but unguarded
1 bypasses reeve
1 exempted
coverage: incomplete
BYPASS export_invoices
registered with the server but neither routed through reeve nor exempted — route it to
a guarded tool, or exempt it with a reason
EXEMPT healthcheck
returns no application data
The report names tools, classes and exemption reasons — never an argument, a principal or a record — so it is safe to print in CI. An exemption without a reason is refused, and one with a reason is listed every time, complete or not.
Fail boot or CI on a gap:
McpInventory.verify! # raises Reeve::IncompleteInventoryError, carrying the reportDispatch through it, and a bypass stops being possible:
def call_tool
name = params.dig(:params, :name)
arguments = params.dig(:params, :arguments).to_h.symbolize_keys
result = McpInventory.dispatch(name, arguments: arguments,
agent: { id: request.headers["X-MCP-Client"] }) do
McpServer.handlers.fetch(name).call(arguments)
end
render json: { jsonrpc: "2.0", id: params[:id], result: serialize(result) }
rescue Reeve::DeniedError => e
render json: { jsonrpc: "2.0", id: params[:id],
error: { code: -32_003, message: e.message } }
end- A routed name runs through
Reeve.invokeunder its class's guard, with the handler block as the body. A registry of blocks needs one guarded class per tool to name its policy, and nothing else — the block still does the work, and what it returns is scoped. Handlers dispatched this way should not callReeve.invokethemselves. - An exempt name runs the block as written.
- Any other name is a tool with no guard, and
unguarded_toolsdecides: refused withunbound_toolunder:deny, the default; run unscoped and recorded withguard: "none"under:allow_with_warning. Recorded either way, so a name the inventory missed lands on the same ledger worklist as an unguarded class.
In the compliance suite, EndpointCoverage compares the run against the inventory. It
passes only when every registered tool is guarded or exempt and the run covered all of
them. It fails when the run claimed the whole endpoint and something bypasses Reeve. A run
narrowed by compliance_tools is reported as a subset — skipped, naming what it left out —
so a retrofit stays green without passing for complete coverage.
Policies are plain objects unless you want Pundit (authorize and scope, two methods).
The ledger is an ActiveRecord table unless you supply your own recorder. Records are
ActiveRecord unless they are not — a plain object with an id works.
Rate limiting, prompt-injection defence, cost control, and connection authentication are out of scope, and the ledger's chain detects tampering rather than preventing it. This library governs what an authenticated agent may touch and what it touched. Keep your existing auth.
Ruby 3.0+, Rails 7.0+. No runtime dependencies. The fast-mcp adapter needs Ruby 3.1+,
because fast-mcp does. The official SDK adapter needs mcp 1.x and runs on Ruby 3.0+. The
ActionMCP adapter needs actionmcp 0.200 to 0.203, Rails 8.1 and Ruby 3.2+.
Built by Victor Velázquez — COO at MagmaLabs and author of The Agentic Engineer. Reeve guards MCP tools in production at MagmaLabs.
MIT. See LICENSE.txt.