mcp-gatehouse
This is an order-desk MCP server for viewing and managing your own orders, with approval gates on destructive actions and full audit logging.
List your orders (
list_orders) — read-only; returns id, customer, status, total and notes for orders that are yours.Look up a single order (
lookup_order) — read-only; shows details for one order, refused if it isn't yours or doesn't exist.Add a note to an order (
add_note) — appends free-text without overwriting anything; runs without approval, accepts an optionalapi_keythat gets masked in the audit log.Cancel an order (
cancel_order) — irreversible and gated: requires human approval (client approval form, else terminal), fails closed if refused/unanswered/nowhere to ask, and shipped orders can't be cancelled.Audit trail — every call, including denials and refusals, is recorded in the audit log.
mcp-gatehouse
Project page & docs: nickgeorgeai.com/open-source/mcp-gatehouse · PyPI
Authorization as a runtime invariant for MCP servers. Every tool call needs a verified caller, an explicit policy, and a decision on the record it acts on, made by the server before the tool runs. If any of those is missing, the call doesn't run. Around that: permission tiers, approval gates, and an audit log of every call.

Most MCP servers hand the model every tool at full strength and keep no
record of what it did. That's fine for a demo. It's not fine the day an
agent has write access to your CRM, your books, or your order system.
mcp-gatehouse is the missing gate, enforced inside the server — no
proxy, no external policy service. It depends only on the official
mcp SDK and
opentelemetry-api, which the SDK already requires.
pip install mcp-gatehouseUpgrading from 0.5? 0.6.0 fails closed. A tool without
authorize=doesn't register, and over stdio a server withoutlocal_caller=denies every call. Pinmcp-gatehouse<0.6until you've migrated; the migration steps are one short list.

The demo server in Claude Code: the model asks to cancel an order, the gate asks you in Claude Code's own UI, and the call runs. Then it tries an order that isn't yours, and the policy refuses it before anyone is asked. The audit log has a line for every call, with who it was for and why it was refused.

The 1:21 demo runs the package's demo server in a terminal: the install, the one-decorator change, a cancel refused and one approved, and the audit log they left. No sound.
What you get
Authorization on the record | Every tool names a policy. The gate loads the record the call is about from the model's arguments, your policy decides on it, and the tool gets that same object. The model can't describe a record into existence or reach one that isn't the caller's. |
No way around the gate | A tool without a policy doesn't register, the server refuses tools, resources, prompts, completions and SDK extension methods or interceptors registered around the gate, and a call with no verified caller is denied. Each opt-out is explicit and marked in the audit log. |
Check and write together | The policy's decision and the tool's write share one transaction you supply, or the write carries the checked state in its own condition. A record that changes after the check is never acted on. |
Lists filtered per item | A tool that returns records gets each one checked: what the caller may not see never reaches the model. |
Permission tiers | Every tool is declared |
Approval gates | Tiers you choose require a sign-off before the tool runs, asked right in the MCP client (Claude Code, Cursor, VS Code) or by any callable you write: a terminal prompt, a Slack ping, a ticket. Fails closed: a gated tool with no approver configured is denied, not waved through. |
Audit log | One record per call — allowed, denied, failed, or cancelled — with UTC timestamps and durations, who each call was for, and the policy's real reason for every refusal, in a documented schema. Append-only JSONL by default, or any sink you give it: a function, OpenTelemetry, your logging pipeline. The answer to "what did the AI actually do, and for whom?" six months later. |
Redaction | Argument keys you name ( |
Denylist | Block a tool outright, whatever its tier. |
Related MCP server: TheeDiscordMCP
Quickstart
from typing import Annotated
from mcp.server.mcpserver import MCPServer
from pydantic import BaseModel
from mcp_gatehouse import (
AccessTier, Allow, AuditLog, AuthorizationRequest, Caller, ConditionalWrite, Deny,
ElicitationApprover, Gatehouse, Load, Policy, terminal_approver,
)
class Order(BaseModel):
"""Your record. Any Pydantic model, dataclass or mapping will do."""
id: str
owner: str
status: str
mcp = MCPServer("order-desk")
gatehouse = Gatehouse(
mcp,
# Ask in the client's own UI; prompt on the terminal if it can't show a form.
policy=Policy(approver=ElicitationApprover(fallback=terminal_approver)),
audit=AuditLog(path="~/order-desk/audit.jsonl"),
# Over stdio nobody signs in, so say who the calls are for.
local_caller=Caller(client_id="local", subject="alice"),
)
def load_order(order_id: str) -> Order | None:
"""Your system of record. None means there's no such order."""
...
def owner_only(request: AuthorizationRequest) -> Allow | Deny:
order = request.resources["order"]
return Allow() if order.owner == request.caller.subject else Deny("not the owner")
@gatehouse.tool(tier=AccessTier.READ, authorize=owner_only)
def lookup_order(order_id: str, order: Annotated[Order, Load(load_order)]) -> str:
"""Look up an order's status."""
return order.status
@gatehouse.tool(
tier=AccessTier.DESTRUCTIVE,
authorize=owner_only,
consistency=ConditionalWrite(), # the cancel's UPDATE checks the order's version
)
def cancel_order(order_id: str, order: Annotated[Order, Load(load_order)]) -> str:
"""Cancel an order. Runs only if it's the caller's and the approver says yes."""
...
mcp.run()That's the whole integration: build your MCPServer exactly as the SDK
docs show, but create the gatehouse first and register every tool through
it. The model sees order_id and nothing else; the gate loads the order,
your policy decides on it, and the tool gets the order the policy saw.
Schema generation (including Annotated[..., Field(description=...)]
parameter docs), transports, and everything else work unchanged. Sync tools
still run in a worker thread, exactly as they would on a bare MCPServer.
Authorization: a runtime invariant
Most servers leave authorization to each tool, and nothing notices when one forgets. Here the server enforces it. Every call needs three things, checked in the server before the tool runs:
A verified caller. That's the identity in the access token the SDK verified for the request. Over stdio, where nobody signs in, it's the
local_calleryou declare. An HTTP request with no verified token is nobody, even on a server that declares a local caller.An explicit policy.
authorize=is required on every tool.A decision on the record itself. The gate loads each
Loadparameter from the model's arguments, gives the records to your policy, and hands the tool those same objects.
If any of the three is missing, the call is denied. Gatehouse doesn't know your business rules. What it guarantees is that they run at the right place, and that nothing gets around them:
A tool without
authorize=raises at registration, so the server doesn't start.The server refuses tools added around the gate. That covers
@mcp.tool()andadd_toolbefore or after the gate is created,MCPServer(tools=...), extension tools, and a tool slipped into the registry. A refused tool is hidden fromtools/listand denied when called.Resources, prompts and completions are other ways to the same data, and they have no policy: a template
orders://{order_id}would read the record a tool checks, for anyone. So the server refuses them too, before or after the gate is created. Content that is the same for every caller (docs, a schema, a price list) goes through@gatehouse.open_resource(uri)or@gatehouse.open_prompt(), and a read without a verified caller is refused. These write no audit line. Anything that depends on who is asking belongs in a READ tool with a policy. Completions are refused outright: the SDK never tells the handler who is asking.An SDK
Extensiongets the same treatment. Its tools and resources are refused with the rest, and so is a server whose extension serves request methods of its own (Extension.methods()) or overridesintercept_tool_call: both answer with no policy and no audit line. What the gate guards is the SDK's public registration surface. Code that writes into the SDK's private registries (a template put straight into_resource_manager._templates), adds a low-level request handler after the gate, or adds request middleware to the low-level server (server.middleware, provisional in the SDK, which wraps every request,tools/callincluded, and can answer before the gate does), runs with your server's trust, like any other code you install in it.Nothing the gate fills can come from the model. A
Loadparameter never appears in the input schema, and registration fails if the SDK would put it there.
Each requirement has a way out, but only one you write down, and the audit log shows it:
Requirement | Applies to | Declared with | Deliberate opt-out | Audit line shows |
Verified caller | every call | the SDK's auth ( |
|
|
Policy | every tool |
|
|
|
Item filtering | tools returning a list of records |
|
|
|
Check and write in one unit | WRITE/DESTRUCTIVE tools that |
|
|
|
Where it sits
Three layers can say no to a tool call. They see different things, and they don't compete:
Agent-framework approvals live in the agent process, beside the model. They see the tool's name and the arguments the model proposed, and can ask a person before the call leaves the agent. They don't see the record, and a server reached by another client never meets them.
Gateways, proxies and policy services sit in front of the server. They see the token, the tool name and the arguments, so they can decide which clients reach which tools, enforce scopes, rate-limit, and route. They don't see the record either, and whether the tool behind them checks it is up to that server.
The gate is the check inside the server, on the record the call is about, for the caller the transport verified. The layers in front assume someone writes that check. This is the one that makes writing it mandatory: a tool without a policy doesn't register.
Use all three. An identity layer issues the token the SDK verifies and the
gate reads. A gateway narrows what reaches the server. Framework approvals
catch the agent's own mistakes early and cheaply. The gate decides on the
record, and keeps the trail. A team with a central policy engine keeps
its rules there and lets the gate call it:
examples/policy_opa.py and
examples/policy_cerbos.py send the caller,
the tool, the action and the loaded record to the engine. An engine that
can't be reached is a denial, and the model is told the call can be
retried, so "not now" doesn't read like "no". on_unavailable=Ask sends
those calls to your approver instead.
By design, mcp-gatehouse is none of the other layers. It is not a
proxy or a gateway, has no control plane, mints or exchanges no tokens,
and has no policy language: policies are Python, or a call to the engine
you already run.
It guards calls through this server, and only those. A script, a service
or another agent that reaches the database or API behind the tools
directly never meets the gate, and nothing the gate does can stop it. To
make the checks hold on every path, enforce them in the backend too. Give
the server the narrowest credential that does its work, not a shared
admin account. Have the backend check the caller itself, as
examples/orders_postgres.py does: the
Transaction factory sets app.subject from the verified caller, and
Postgres row-level security limits every query to that user's rows,
whoever connects. Don't hand other clients a credential that skips those
checks. Short-lived, narrowly scoped tokens for the services behind the
tools come from your identity provider. The gate checks the ones it
receives (scopes=, request.claims) and passes the caller on, but
doesn't issue them.
It is also not a workflow layer. The gate checks one call at a time and
keeps no workflow state, so a job that another agent picks up after a
dropped call resumes from wherever your workflow stores it, not from the
gate. Nor does it confirm what landed. outcome: "ok" means the tool
returned without raising; under Transaction it also means the commit
succeeded. For a tool that calls a calendar, a CRM or a payment service,
it means the call returned, not that the change is there. Two things
help a retry: Load reads the record again, so the policy decides on its
current state, not the state the last attempt saw, and a policy that
checks status refuses to cancel an order twice. Idempotency keys and
"did it land" checks belong to the tool or the workflow above it.
Policies
A policy is any callable, sync or async, that takes an
AuthorizationRequest and returns one of three decisions:
Allow().Deny(reason).Ask(reason): a person decides. The configured approver is asked, and sees the reason.Askwith no approver is a denial, whateverfail_closedsays.
Only a decision counts. A policy that returns True, None or anything
else, or that raises, has denied the call.
The request carries:
caller: who the call is for;resources: the loaded records;arguments: what the model sent, read-only;claims: the verified token's claims, read-only. They go to the policy only and are never logged.
def can_cancel(request: AuthorizationRequest) -> Decision:
order = request.resources["order"]
if order.owner != request.caller.subject:
return Deny("not the owner")
if order.status == "shipped":
return Deny("already shipped", message=f"Order {order.id} has shipped.")
if order.total > 500:
return Ask("order over $500")
return Allow()The model gets the same answer for every refusal on authorization: "'X' is
not permitted for this caller." That covers a record that doesn't exist, one
that isn't theirs, and a loader or policy that failed, so it can't probe
which orders exist. The audit log records the real reason (not found: order, policy: not the owner). Deny(..., message=...) tells the model
more, when that's safe to say.
Load(loader, describe=..., fingerprint=..., changed_values=...):
The loader's parameters name the tool's arguments it loads from. A loader that returns
Nonemeans not found.The approver sees the record, not only the arguments the model chose. By default that is its fields as the audit log shows them, secrets masked (
order: id=4417 · customer=Blue Ridge Cabinets · status=packed · total=812.0);describereplaces it with a line you write ("order 4417 · Blue Ridge Cabinets · $812.00").An approval binds to the record's state, by default a redacted snapshot of it, or what
fingerprintreturns. If the record changes while a person decides, the call is refused rather than run on something they never saw. The snapshot holds masked fields as«redacted», so a change to only a masked field (a rotatedapi_key, say) goes unseen; return it fromfingerprintif it matters. On a tier that requires approval, a record must be a Pydantic model, a dataclass or a mapping, or have afingerprint.A refusal for a changed record says what changed, and asking again shows the person the same thing first, so the second question doesn't read like the first:
'cancel_order': the record changed while the approval was pending, so the approval no longer applies. Nothing was done. What changed: order.total: 812.00 → 812.01. Calling again asks the person again, showing them what changed. Changed since you were last asked: order.total: 812.00 → 812.01. The AI wants to run cancel_order …Over the 2026-07-28 round trip there is no refusal: a stale answer is asked again the same way, and its
pendingline says so (approval asked again: resource changed while awaiting approval). A masked field is named without its values (order.api_key changed), and so is every field of a record whoseLoadhasdescribe, since you chose what the person sees; passchanged_values=Truewhen its fields may be shown. A change onlyfingerprintsees readsorder: a field that isn't shown changed. Custom approvers get the lines inApprovalRequest.changes, and the audit line lists the field names inchanged. What was asked is remembered per process for an hour: a question asked on another replica, or longer ago, still binds the same way but shows no changes.
Deadlines
A call gets five seconds to load its records and reach a decision: the
loaders, the policy and any Scope, together. Past that it is denied,
logged as authorization timed out: policy (or loading order, or
scope owner), and the tool doesn't run. The model is told this isn't a
refusal and the call can be retried, so "not now" doesn't read like "no".
Policy(authorization_timeout=2.0) # every tool
@gatehouse.tool(authorize=report_policy, authorization_timeout=30) # one tool
@gatehouse.tool(authorize=refund_policy, on_authorization_timeout=Ask)on_authorization_timeout=Ask puts a call whose policy ran out of time
to the approver, with the reason authorization timed out, instead of
denying it. A refund then waits for a person rather than being lost. A
loader or Scope that runs out still denies: there is no record yet to
ask about. authorization_timeout=None turns the deadline off, and every
audit line for that tool says "authorization_deadline": "off".
Python can't stop a thread. A sync loader or policy past the deadline is
abandoned: the call ends, and the thread finishes in the background with
its result dropped. Those threads are the gate's own, not the pool sync
tools draw on, so a hung policy never leaves a sync tool without a thread.
Each tool has its own 40 of them, so a policy that hangs on one tool
doesn't make another tool's authorization wait. An abandoned thread keeps
its place until it really returns, and the gate says so on stderr: a
policy that never returns can tie up at most its own tool's 40 threads,
after which that tool's calls are denied at the deadline without starting
another. Give every blocking call in a sync policy its own timeout,
shorter than the deadline.
Inside a sync Transaction every step runs in one thread, so the
deadline is checked between steps: a slow policy runs to the end, then
counts as late, and the transaction rolls back. That thread is the tool's
own too, one of 40 per tool, so a policy hung inside a transaction never
takes a thread from sync tools elsewhere. But it isn't abandoned: it holds
its thread, and its call, until it returns. Set the database's
statement timeout for a query that hangs there. An async policy that
blocks without awaiting, such as a sync HTTP call inside async def,
stalls the whole server, and no deadline can reach it.
The check and the write
Loading once and handing over means the tool acts on the object that was checked. It doesn't stop that record changing in the database between the check and the write. A WRITE or DESTRUCTIVE tool that loads a record must say how that window is closed:
Transaction(factory).factory(caller)returns your context manager, sync or async. The gate runs the load, the policy, the tool and the commit inside it, and a refusal or an error rolls it back.Lock the row in the loader (
SELECT … FOR UPDATE) and the decision still holds when the tool writes.Loaders and the tool reach the transaction through
current_transaction().A sync transaction runs entirely in one worker thread, so drivers tied to their thread are safe. Everything inside it must then be sync. With an async transaction, the loaders and the tool are async.
The gate never holds a transaction open while a person decides. It asks first, then opens the transaction, reloads and checks again.
ConditionalWrite(). The write carries the checked state in its own condition:UPDATE … WHERE id = ? AND version = ?. When it matches nothing, the tool raisesConflict. The log recordsoutcome: "conflict"and the model is told the record changed. The gate can't see your query, so this one is your promise.AcceptRace("why"). Accept the window on purpose. The reason goes on every audit line.
The gate guarantees that the check and the write share one unit, in that
order. Isolation (row locks, SERIALIZABLE) is your database's job.
examples/orders_postgres.py shows all of
it on Postgres.
Lists
"May alice update invoice 123?" is a check. "Show alice her invoices" is a filter, and filters belong in the data layer. The gate wires each layer to the verified caller and backstops it:
Row-level security. The transaction factory gets the caller, so it can
SET LOCAL app.subjectand let Postgres RLS limit every query the tool runs.Scope(fn). This fills a hidden parameter with a query filter computed from the caller: an owner, a tenant, or the IDs a relationship-based engine lists. Your query uses it.authorize_items=, the gate's backstop. A tool that returns a list of records must declare it. The gate checks each item it returned (action="read",resource=item), and onlyAllowkeeps one.With layers 1 and 2 working, it withholds nothing.
The
okline countswithheld, and flagsscope_mismatchwhen aScopewas in force. A nonzero count is an alarm that the query and the policy disagree.
The gate can only filter records it can see as items. A tool that formats rows into a string gets the call-level check alone, so return records. Filtering after the fetch also shrinks pages, so correct paging needs layer 1 or 2.
Allowed isn't the same as wanted
Perfect enforcement still lets a prompt-injected agent do anything the user is allowed to do. Authorization answers "may this happen?", not "did the user ask for this?". The gate holds two levers:
Task-scoped credentials make "allowed" as small as the task.
scopes={"orders:cancel"}on a tool denies a token without that scope, before anything loads.A policy can read
request.claims. It can require that the token'sauthorization_details(RFC 9396) name this exact order, so a token minted for "cancel 4417" can't cancel 4418. It can also checkact(RFC 8693) to tell an agent acting for alice from alice herself.Issue short-lived, down-scoped tokens per task. The gate enforces them; it doesn't mint them.
Confirmation for high-impact actions. DESTRUCTIVE needs approval by default, and
Askadds it on your conditions. The approver sees the record (describe) and the reason, not only the model's arguments, which gives a person the chance to spot an action nobody asked for. Elicitation trusts the client to show the form to a person. For the tools that matter most, approve out-of-band (Slack, a ticket), where neither the model nor a compromised client can answer.
What no gate can do is infer intent. It limits the blast radius, puts a person in front of what can't be undone, and keeps a trail that makes misuse visible afterwards.
Approve in the client
ElicitationApprover puts the question in front of the person using the
MCP client, as a form with one box to tick. It shows the tool and its tier,
why the policy asked, who the call is for, the arguments (secrets already
masked) and each record the call acts on, as the server loaded it:
Approval needed (order over $500). The AI wants to run cancel_order (destructive) for "nick" via client "local" with:
{"order_id": "4417"}
on order 4417 · Blue Ridge Cabinets · packed · $812.00MCP calls this elicitation. Claude Code, Cursor and VS Code support it. The model can't answer the form, and you run nothing beside the server.
It works under both protocol revisions in use:
Up to 2025-11-25 the form goes to the client mid-call and the gate waits for it, under
approval_timeoutlike any approver.From 2026-07-28 there's no channel for that. The call hands the question back to the client and runs when the client calls again with the answer. The SDK seals that round's state and binds it to the tool and its exact arguments. The gate also checks that the answer is to the question it asked, that it arrived within
approval_timeout(an hour if none is set), and that each approval runs its call only once.
Anything but a ticked box (decline, cancel, closing the form, an unticked
box, a malformed answer) is a refusal. When the client can't be asked, the
fallback decides; with no fallback, the call is denied. A tool that runs
its own multi-round input flow, through Resolve(...) parameters or by
returning InputRequiredResult, gets the fallback too from 2026-07-28,
since one call has one such channel. Up to 2025-11-25 the form goes over
its own request, separate from the tool's rounds, so the client is asked
as usual.
Used approvals are remembered in an ApprovalStore, so each runs its call
once. The default, MemoryApprovalStore, remembers per process. That is
enough while the SDK's request-state key is per process too, which it is
by default. Each process seals its questions with a key of its own, so an
approval minted before a restart, or by another replica, fails the SDK's
seal check before the gate or its store ever sees it.
Replicas behind a load balancer, or a server that should honour approvals across a restart, need two things. First, every replica uses the same request-state key and the same server name, which the SDK binds each question to:
from mcp.server.request_state import RequestStateSecurity
KEY = os.environ["MCP_REQUEST_STATE_KEY"] # 32+ random bytes, the same on every replica
mcp = MCPServer("order-desk", request_state_security=RequestStateSecurity(keys=[KEY]))Second, they share the store, or one approval runs its call once per
replica, and once more after each restart within approval_timeout. A
store is anything with spend(nonce, expires) -> bool. Two are examples
to copy:
examples/approval_store_sqlite.py,
standard library only, for replicas on one host, and
examples/approval_store_postgres.py,
on psycopg, for replicas on several. Both spend each nonce once under
concurrent spenders and sweep expired ones. A store that raises denies
the call, logged as approval store error.
ElicitationApprover(store=PostgresApprovalStore(os.environ["APPROVALS_DSN"]))To rotate the key without dropping questions in flight, the SDK takes a
ring: keys=[old, new], then keys=[new, old], then keys=[new].
Elicitation trusts the client to show the form to a person. A client or hook set to accept forms on its own can approve too. When the approval must come from outside the client, use an out-of-band approver instead.
Other approvers
terminal_approver asks on the controlling terminal (/dev/tty), never
stdin — over stdio, stdin is the protocol pipe, so a plain input()
approver would corrupt it. An approver is any callable, sync or async,
that takes an ApprovalRequest and returns True to allow; sync ones run
in a worker thread from a pool of their own, so a human taking their time
doesn't stall other calls, and a pile of pending approvals can't take the
threads your sync tools need. If the approver raises (Slack down, ticket
API timing out), the call is denied and the failure is logged.
Give approvals a deadline so a sign-off nobody gives doesn't hang the call:
Policy(approver=terminal_approver, approval_timeout=120)Past it, the call is denied and logged as approval timed out. Approvers
see the deadline as request.deadline (a time.monotonic() value), and
terminal_approver withdraws its prompt when it passes. A sync approver
should return by then too. One that doesn't finishes in the background, its
answer dropped, with a warning on stderr. Its thread keeps one of the tool's
40 approver threads until it returns. So an approver that never returns can
tie up at most its own tool's 40, and once they are all taken, that tool's
later approvals time out without starting more. Other tools keep their own
40. With no timeout set, the gate waits as long as the approver takes.
Under the default policy, DESTRUCTIVE requires approval and everything
is audited. Gate writes too with one line:
policy = Policy(require_approval=frozenset({AccessTier.WRITE, AccessTier.DESTRUCTIVE}), approver=terminal_approver)Add your own secret-bearing keys without losing the defaults:
from mcp_gatehouse import DEFAULT_REDACT
policy = Policy(redact=DEFAULT_REDACT | {"card_pin"}, approver=terminal_approver)The audit log
One record per call, whatever happened to it:
{"ts": "2026-11-06T14:02:11+00:00", "call_id": "4b1e0c9a6f2d47f1a3c85e0d2b7f9a61", "request_id": "7", "trace_id": "0af7651916cd43dd8448eb211c80319c", "span_id": "b7ad6b7169203331", "tool": "list_orders", "tier": "read", "outcome": "ok", "arguments": {}, "duration_ms": 0.31, "timings_ms": {"authorize": 0.05, "tool": 0.31, "filter": 0.04, "total": 0.42}, "withheld": 1, "caller": {"client_id": "local", "subject": "alice", "issuer": null, "scopes": [], "source": "local"}, "authz": "open"}
{"ts": "2026-11-06T14:02:38+00:00", "call_id": "…", "request_id": "8", "tool": "add_note", "tier": "write", "outcome": "ok", "arguments": {"order_id": "4417", "note": "call back", "api_key": "«redacted»"}, "duration_ms": 1.08, "caller": {…}, "authz": "allow", "resources": {"order": {"order_id": "4417"}}, "consistency": "conditional"}
{"ts": "2026-11-06T14:03:05+00:00", "tool": "cancel_order", "tier": "destructive", "outcome": "denied", "reason": "policy: someone else's order", "arguments": {"order_id": "4420"}, "caller": {…}, "authz": "deny", "resources": {"order": {"order_id": "4420"}}, "consistency": "conditional"}
{"ts": "2026-11-06T14:05:40+00:00", "tool": "cancel_order", "tier": "destructive", "outcome": "denied", "reason": "approver refused", "arguments": {"order_id": "4417"}, "caller": {…}, "authz": "ask", "resources": {"order": {"order_id": "4417"}}, "consistency": "conditional"}The fields, and when each appears. The same table, as a JSON Schema the
test suite checks every line against, is
docs/audit-line.schema.json. No other
field is ever written.
Field | Type | When |
| string, ISO-8601 UTC | always |
| string, 32 hex | always: the gate's id for the call, the same on every line it writes. |
| string | when a live request is behind the call: its JSON-RPC id, cut to 128 characters. The client's choice, unique only per session |
| string, 32 and 16 hex | when the call runs in an OpenTelemetry trace: the client's |
| string, 32 hex | on the round that answers a round-trip approval: the |
| string | always |
|
| always; |
|
| always |
| string | every outcome but |
| object | always: the model's arguments after redaction. Never what the gate filled |
| number |
|
| object: | every line written by the tool's gate (all but the |
| object: | once a caller is known: every line but the |
|
| once the policy decided ( |
| object: each | every line of a tool that loads records. Never the record itself |
|
| every line of a tool with |
|
| every line of a tool with |
| string | with |
|
| every line of a tool with |
| integer |
|
| integer | with |
|
| with |
| array of strings | denials with reason |
| string | only on the stderr copy of a line that didn't reach the sink: the exception type when the sink raised, |
The outcomes: ok, the tool ran. denied, the gate refused, and reason
says why. error, the tool raised, or the transaction or item filtering
failed. conflict, a conditional write matched nothing because the
record changed. pending, the approval was asked in the client over the
2026-07-28 round trip: the verdict follows on a line of its own when the
client comes back, so a pending line with nothing after it is a question
nobody answered. cancelled, the client gave up or the server shut down
before the call finished: reason says when. authorizing and awaiting approval mean the tool never ran. tool running comes with duration_ms,
and the tool may have done part of its work. A sync tool can't be stopped
partway: its worker thread runs to the end, and the line says ok or
error as usual. A sync policy or loader can't be stopped either, but
the gate takes the cancellation as soon as it returns, before the tool
starts. Inside a Transaction that rolls the transaction back. The gate
only writes the line; the cancellation goes on as it would without it.
Tracing a call
call_id groups one call's lines; continues joins the two rounds of a
round-trip approval. To go further, out to the agent and the model, use
the trace. The MCP SDK opens an OpenTelemetry span for every request,
parented on the traceparent the client sends in the request's _meta,
and the gate writes that trace's trace_id and span_id on the line.
Find the line from a slow or failed span in your tracing backend, or the
span from a line. Nothing to configure: opentelemetry-api comes with
the SDK, and with no OpenTelemetry SDK set up the client's trace still
comes through.
The gate doesn't record model token usage, and has no field a client can
fill with it. It never sees the model, a number the client reports is
unverified, and the trace already joins the two: put token counts on the
client's LLM spans, as the OpenTelemetry GenAI conventions do
(gen_ai.usage.input_tokens), and they sit in the same trace as the
gate's line.
A retry by the model is a new call with a new call_id. The gate can't
tell it is a retry; the trace can, when the agent keeps the turn in one.
Sinks
AuditLog(path=...) appends JSON lines to a file, and AuditLog(stream=...)
to a text stream. AuditLog(sink=...) hands each record, as a dict, to
anything with a write(record) method:
from mcp_gatehouse import AuditLog, CallableSink
AuditLog(sink=CallableSink(queue.put)) # your own function
AuditLog(sink=CallableSink(lambda r: log.info("audit", extra=r))) # the logging moduleThree sinks ship with the library, none needing anything beyond it:
JsonlSink(path=...) or JsonlSink(stream=...), which is what path=
and stream= use, CallableSink(fn), and BufferedSink, below. For OpenTelemetry logs, copy
examples/audit_otel.py: one log record per
audit record, the record as the body and the fields worth filtering on as
attributes. An HTTP collector or a logging pipeline is a CallableSink
away.
JsonlSink(path=...) appends each record with one unbuffered write of
the whole line, so the file only ever holds whole lines: a write that
fails part way (a full disk) is cut back off, and that record goes to
stderr as below and never turns up in the file later as well. A stream
you pass in is written and flushed per record, and is yours to manage.
Records reach the sink one at a time, so it needn't be thread-safe. A sink
that raises doesn't lose the record and doesn't fail the call: the gate
writes the line to stderr with a sink_error field naming the exception
type, and goes on. Watch stderr for sink_error if the sink is the only
copy of the trail. AuditLog.close() calls the sink's close() when it
has one.
A sink is written on the request path, so a slow one (an HTTP collector,
a remote log) slows every call. Wrap it in BufferedSink to write it from
a background thread instead:
AuditLog(sink=BufferedSink(CallableSink(post_to_collector), maxsize=10_000))write puts the record on a bounded queue and returns at once; one
thread writes the queue to the inner sink in order. When the queue is
full the call doesn't wait. The record goes to stderr with
sink_error: "queue full" instead of the queue, so stderr is then its
only copy. Size maxsize for your bursts and alarm on sink_error.
close() writes everything already queued, then closes the inner sink;
it also runs at exit for a buffer nobody closed. A record written after
close() goes to stderr with sink_error: "sink closed".
A signal's default action skips exit hooks, so on SIGTERM (docker stop,
systemd, or the MCP Python SDK's stdio client, which sends it 2 s after
closing stdin) the queue would go nowhere. A BufferedSink created on the
main thread therefore installs a SIGTERM handler, unless SIGTERM is
already handled: yours, or a web server's, is never replaced. It writes
every record still queued to stderr with sink_error: "terminated", then
lets the default SIGTERM end the process. The record being written at
that moment goes to stderr too, so it may also be in the inner sink. To
drain into the inner sink instead, handle SIGTERM yourself and close the
log there:
import signal
import sys
audit = AuditLog(sink=BufferedSink(CallableSink(post_to_collector), maxsize=10_000))
def on_sigterm(signum, frame):
audit.close() # drains the queue, then closes the inner sink
sys.exit(0)
signal.signal(signal.SIGTERM, on_sigterm)Who the call was for
On a server that signs callers in with the SDK's auth (a
token_verifier, over streamable HTTP or SSE), every audit line also
names the caller, taken from the access token the SDK verified for that
request:
{"ts": "2026-11-05T09:14:02+00:00", "tool": "cancel_order", "tier": "destructive", "outcome": "ok", "arguments": {"order_id": "4417"}, "duration_ms": 3.1, "caller": {"client_id": "support-agent", "subject": "alice", "issuer": "https://login.example.com", "scopes": ["orders:read", "orders:write"]}}It is read per request, so a token the client refreshes mid-session is
logged as the new one. Approvers get the same thing as request.caller
(a Caller), and terminal_approver names the user and the client in
its prompt, so whoever signs off knows whose request it is:
⚠ approval needed → cancel_order (destructive) {'order_id': '4417'}
on order 4417 · Blue Ridge Cabinets · packed · $812.00
asked because: order over $500
for "alice" via client "support-agent"
allow? [y/N]An approver can act on it too:
async def approver(request: ApprovalRequest) -> bool:
caller = request.caller
if caller is None or caller.subject is None:
return False # no signed-in user to ask on behalf of
# ask_in_slack and manager_of are yours to write. A subject is unique
# only per issuer, so look people up by both.
return await ask_in_slack(request, notify=manager_of(caller.issuer, caller.subject))subject is only as good as your token verifier. Fill in
AccessToken.subject (and claims with iss), or the log can name only
the client application, not the person. Gatehouse never logs the token
itself, but it does log client_id and subject as your verifier sets
them, so keep the token out of both (some API-key setups use the key as
the client ID). A subject can be an email address or other personal
data, and redact doesn't cover it, since redaction applies to tool
arguments: keep the log's retention in line with that. Over stdio nobody
signs in: the lines name the local_caller the server declared, marked
"source": "local", and without one every call is denied.
What the gate verifies, and what it trusts
The gate checks these itself, every call: the tool was registered through it and has a policy; the request has a caller; the loader ran and found the record; the policy ran on that record and returned a decision; an approval answers the question asked, about the record in the state it was asked about, once; and nothing the gate fills came from the model. The rest it takes on trust from something you configured. Each row says what to do when that trust isn't acceptable.
Taken on trust | What the gate relies on | When that isn't acceptable |
The token verifier | Over HTTP the caller is whatever the SDK's | Use a verifier that checks signature, issuer, audience and expiry against your identity provider, and fills in |
| Whoever starts the server process is that caller. The gate can't tell the user from another program running under their account. | Serve over streamable HTTP with the SDK's auth and drop |
The client showing elicitation forms to a person |
| Use an out-of-band approver (Slack, a ticket, a queue) where neither the model nor the client can answer, as |
The | You promise the write carries the checked state in its own condition and raises | Use |
| You accept that the record may change between the check and the write, for the reason you gave. The gate only records it on every line. | Don't. Close the window with |
Your loader and your policy | The record is what the loader returned; the decision is what the policy returned. A loader that reads the wrong row, or a policy with a hole, is enforced faithfully. | Load through the database's own access control (row-level security under the caller's identity, as |
The audit sink and the approval store | A sink that raises gets its line on stderr; a store that raises denies the call. Where the records then go, and whether the store is shared by every replica, is the deployment's. | Ship the sink's output somewhere append-only and read |
Try the demo
The package ships a runnable order-desk server with all three tiers wired
up. Every order has an owner. Over stdio the server declares that calls are
for you, the user running it, so you see and change only your orders: order
4420 is someone else's. cancel_order refuses an order that has shipped,
and needs your approval for the rest, asked in the client when it can show
a form, with a terminal prompt as the fallback. Above $500 the approval
says so. Add it to any MCP client that speaks
stdio. For Claude Code:
claude mcp add gatehouse-demo -- uvx mcp-gatehouse --audit-log /tmp/gatehouse-audit.jsonlFor Claude Desktop, in claude_desktop_config.json:
{
"mcpServers": {
"gatehouse-demo": {
"command": "uvx",
"args": ["mcp-gatehouse", "--audit-log", "/tmp/gatehouse-audit.jsonl"]
}
}
}Claude Desktop doesn't show approval forms yet, and it starts servers
with no terminal, so there cancel_order is always denied (fail closed)
and stderr says why. Reads and notes work as anywhere else. To approve a
cancel, use a client with forms, such as Claude Code.
Or run mcp-gatehouse-demo yourself after pip install mcp-gatehouse.
Ask the model to list the orders, look up 4420, and cancel one, then watch
each verdict land in the audit log, with the policy's reason when it says
no. The audit log goes to --audit-log, else
$MCP_GATEHOUSE_AUDIT_LOG, else ./audit.jsonl — falling back to
~/.mcp-gatehouse/audit.jsonl when the working directory isn't writable
(desktop clients often launch servers from /). The server prints the
path it chose to stderr.
In a client that supports elicitation (Claude Code, Cursor, VS Code),
cancel_order brings up an approval form in the client: tick the box to
let it run. An approval nobody gives is denied after two minutes.
Other clients get the terminal fallback, which needs the server to have a terminal it can ask on. Whether it gets one depends on how the client starts it:
TypeScript SDK clients (the
StdioClientTransportin 1.x and 2.x) keep the server in the client's terminal session. Start such a client from an ordinary terminal, one not running a full-screen program, and the prompt appears there. An unanswered prompt is denied after two minutes.Python SDK clients (
stdio_clientin 1.x and 2.x), and anything built on them, start every server in a session of its own. The server has no controlling terminal even when you run the client from one, so it can't prompt:cancel_orderis denied, and stderr says why.Desktop apps that launch servers in the background give them no terminal, and full-screen terminal UIs are using theirs. Denied too.
Every denial is the gate failing closed, as designed. Where the prompt
can't reach you, approve out-of-band instead: an approver is any callable,
so it can post to Slack, open a ticket or wait on a queue.
examples/orders_server.py is a trimmed copy of the demo server, as a
copyable template.
Design notes
Enforcement lives inside the server, at the tool boundary. A proxy can't see your tools' semantics, and a policy service is one more thing to deploy. A 40-person plant doesn't have a platform team; this is a few small classes and a JSONL file.
Fail closed. Security defaults that quietly allow are worse than none. That includes redaction: argument values the scrubber can't take apart (arbitrary objects, bytes) are replaced with an opaque placeholder rather than passed through, and exception messages stay out of the log — only the exception type is recorded, because error text loves to embed the very values you just redacted.
The audit log records denials, errors and cancellations, not just successes — the calls that didn't happen are half the story, and a call cut off halfway may still have done something.
A blocking terminal approver and the stdio transport don't mix — stdout/stdin are the protocol pipe.
terminal_approverprompts on/dev/ttyfor exactly that reason, and denies when there's no terminal or a full-screen program has it in raw mode. Asking in the client (elicitation) sidesteps the terminal entirely. When the approval must not come from the client, approve out-of-band: Slack, a ticket, a queue.Opt out on purpose, never by omission. As with CSRF protection in a web framework, the protection is on unless you switch it off for one tool, in writing (
any_caller,any_item,AcceptRace("why")), and the audit log shows every place you did.What this is not: authentication, transport encryption, a sandbox, or a judge of intent. It enforces your policy on the record, for the caller the SDK authenticated, but it can't tell an action the user wanted from one a manipulated agent chose within their rights. Resources and prompts are refused unless you open them; anything per caller belongs in a READ tool. It's a gate inside your server, not a perimeter around it. See SECURITY.md.
Compatibility
Targets the official mcp Python SDK
v2.x (mcp>=2.3,<3) and Python 3.10–3.14. The gate guards the SDK's
tool registry, which it reaches through 2.3's internals; on an SDK where
they aren't there, creating a Gatehouse raises rather than run unguarded. Ships type information
(py.typed). Release notes: CHANGELOG.md.
| SDK | Server class |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The public API (Gatehouse, Policy, AuditLog, AccessTier) is
unchanged across that line, as promised, with one deliberate exception:
0.6.0's authorization invariant. Every tool now needs authorize=, a
server needs a verified or declared caller, a WRITE or DESTRUCTIVE
tool that loads a record needs consistency=, and authorization that
takes longer than five seconds is denied. See
CHANGELOG.md for the migration. Porting a v1 server is two
import edits — FastMCP became MCPServer and moved to
mcp.server.mcpserver; see the SDK's
migration guide.
Staying on SDK v1 needs no action: 0.1.x pins mcp<2, so pip keeps
resolving it. That line is closed to features but still gets security
fixes.
Who built this
Nick George — I design and run MCP servers in production for a mid-market reverse logistics-tech company, and build them for businesses at nickgeorgeai.com. This library is the permission-and-audit discipline from those builds, extracted. Why I built it, and how it works in plain words, is on the project page.
If you're an owner or operator wondering what MCP even is, start with the plain-English guide: What is an MCP server?
License
Available Tools
4 toolsadd_noteA
Append a note to one of your orders. Existing notes are kept — this never overwrites or cancels anything. Runs without approval, and every call is recorded in the audit log. To actually stop an order, use cancel_order.
Inputs: note (required), order_id (required), api_key. Returns: result
cancel_orderADestructive
Cancel one of your orders. Irreversible, so it is gated: a human must approve before it runs, in this client's approval form if it shows one, else on the server's terminal. An order that has shipped can't be cancelled. If the approver refuses, doesn't answer within two minutes, or there is nowhere to ask, the call is denied and the refusal is logged. To record information without cancelling, use add_note.
Inputs: order_id (required). Returns: result
list_ordersARead-only
List the orders on the desk that are yours: id, customer, status, total and notes. Read-only. Start here to find the order ID that lookup_order, add_note and cancel_order need.
Inputs: no named parameters. Returns: result
lookup_orderARead-only
Look up one of your orders: customer, status, total and notes. Read-only; changes nothing. Refused if the order isn't yours or doesn't exist.
Inputs: order_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool maps to a distinct operation on a distinct resource: bulk read (list_orders), single read (lookup_order), append-only mutation (add_note), and destructive mutation (cancel_order). The descriptions explicitly cross-reference each other ("start here to find the order ID that lookup_order… need", "to actually stop an order, use cancel_order"), so an agent cannot reasonably misselect.
All four names follow a uniform snake_case verb_noun pattern (list_orders, lookup_order, add_note, cancel_order). The verbs themselves are semantically distinct and consistent with their read/write/destructive nature.
Four tools is a tight, well-scoped surface for an order-desk agent covering read, annotate, and cancel. It sits at the low end of the healthy 3-15 range, so it is slightly thin but nothing feels redundant or missing for the stated purpose.
The core lifecycle — discover orders, inspect one, annotate, cancel (with irreversibility warnings) — is fully covered with no dead ends. Gaps are minor workarounds rather than blockers: list_orders exposes no filtering/pagination, and there is no order update, refund, or shipping-status operation.
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
- Discortics - Discord BotDeprecatedcom.discortics
Set up and manage your Discord server from MCP: channels, roles, verification, tickets and security.
Create, deploy, and operate MCP servers directly from your GitHub repositories.
A MCP server built for developers enabling Git based project management with project and personal…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA least-privilege enforcement proxy for MCP servers. It sits between MCP clients and upstream servers, enforcing tool policies, hiding denied tools, requiring human approval for risky actions, and providing a structured audit trail.MIT
- AlicenseBqualityDmaintenanceLocal MCP server for inspecting and managing an allowlisted Discord server via Discord's REST API, with safety modes, idempotent JSON blueprints, and destructive-operation safeguards.271MIT
- AlicenseAqualityDmaintenanceA security-first MCP server for managing Whatbox slots with structured read-only inspection and approval-gated mutations, including storage, services, website deployment, and torrent control.30MIT
- AlicenseNot gradedqualityDmaintenanceEnforces identity-based access control and audit logging for MCP servers, letting you grant fine-grained tool permissions to users and systems while failing secure by default.MIT