mcp-gatehouse is a permissions, approval, and audit library for MCP (Model Context Protocol) servers, built on top of the official Python SDK, with all enforcement carried out inside the server, at the tool boundary. It is designed to solve the problem that most MCP servers hand all tools to the model with full permissions and keep no record of operations, making it suitable for production environments where agents need to write to a CRM, ledger, or order system.
Main capabilities
- Permission tiers: Define the levels of operations the AI can read, write, and is forbidden from performing.
- Approval gates: Under the default policy, destructive operations require approval; the approver can be any synchronous or asynchronous callable object that receives an ApprovalRequest and returns True to allow. Synchronous approvers run in a worker thread and do not block other calls.
- Audit logging: Record all operations, including denials and errors. By default, logs are output to the path specified by --audit-log, otherwise $MCP_GATEHOUSE_AUDIT_LOG, otherwise ./audit.jsonl; when the working directory is not writable, it falls back to ~/.mcp-gatehouse/audit.jsonl. The server prints the chosen path to stderr.
- Sensitive information redaction: Sensitive parameter values that cannot be decomposed (such as arbitrary objects or bytes) are replaced with opaque placeholders; exception messages do not enter the logs, only the exception type is recorded, because error text may embed already-redacted values.
- Fail closed: The secure default is designed to deny rather than allow. For example, without a terminal, the approver denies
- Terminal approver (terminal_approver): Prompts on the controlling terminal /dev/tty rather than stdin, because in stdio transport stdin is the protocol pipe. When the approver raises an exception, the call is denied and the failure is logged.
Usage
Integration is the same as in the official SDK documentation, except that tools are registered through gatehouse. Schema generation (including Annotated[..., Field(description=...)] parameter documentation), transport methods, etc. remain unchanged—the guard preserves the function signature. Synchronous tools stillRuns in a worker thread. Example: after building MCPServer, register tools with gatehouse. Under the default policy, DESTRUCTIVE requires approval, and all operations are audited. You can enable write approval with one line of code and add your own sensitive keys without losing the defaults.
The package ships with a runnable order desktop server in which all three tiers are wired in, along with a terminal prompt approver. It can be added to any MCP client that supports stdio, for example by configuring it in Claude Desktop's claude_desktop_config.json. Or run mcp-gatehouse-demo after pip install mcp-gatehouse. Have the model list orders and cancel one, then watch the verdicts land in the audit log.
When to use it
- Production systems that need to give AI agents write access but still need control.
- Small organizations without a platform team (for example, a 40-person factory) that can implement permissions and auditing with just a few classes and a JSONL file.
- Scenarios where you want to implement security gating inside the server without introducing a proxy or an external policy service.
Limitations
- It is not authentication, transport encryption, or a sandbox. It is a gate inside the server, not a perimeter defense. See SECURITY.md for details.
- The blocking terminal approver is incompatible with the stdio transport, because stdout/stdin are the protocol pipe. terminal_approver prompts on /dev/tty and denies when there is no terminal. Real deployments should approve out of band: Slack, tickets, queues.
- The target platform is the official mcp Python SDK v2.x (mcp>=2,<3) and Python 3.10–3.14. Type information is included (py.typed).
- The public API (Gatehouse, Policy, AuditLog, AccessTier) remains unchanged in that line. Porting from a v1 server requires only two import edits: FastMCP becomes MCPServer and moves to mcp.server.mcpserver; see the SDK migration guide.
- Continuing to use SDK v1 requires no action: 0.1.x pins mcp<2, so pip will still resolve it. That line is closed to new features but still receives security fixes.
Other information
Author Nick George designs and runs production MCP servers at a mid-sized reverse logistics technology company, and builds such servers for enterprises at nickgeorgeai.com. This library is the permissions and auditing discipline extracted from those builds. If an owner or operator wants to know what MCP is, they can start with the approachable guide "What is an MCP server?".
