How the local interceptor works

Architecture

┌──────────────────────┐  MCP JSON-RPC   ┌────────────────────┐  evaluate-action  ┌────────────────────┐
│  Claude Code /       │ ──────────────▶ │  Sentrail local    │ ────────────────▶ │  Sentrail cloud    │
│  Cursor / Codex      │                 │  (localhost:3773)  │                   │  policy engine     │
│                      │ ◀────────────── │                    │ ◀──────────────── │                    │
└──────────────────────┘  allow/block/   └────────────────────┘  decision +       └────────────────────┘
                          approval-msg            │              approval status
                                                  │ if allowed / approved
                                                  ▼
                                        ┌────────────────────┐
                                        │  Upstream MCP      │
                                        │  server            │
                                        └────────────────────┘

The local proxy speaks the MCP JSON-RPC protocol. Your agent connects to http://localhost:3773 instead of the upstream server. The proxy intercepts every tools/call, classifies the command, and asks the Sentrail cloud policy engine for a decision before forwarding.

What gets intercepted

Shell commands

The proxy classifies bash, shell, terminal, execute_command, run_command, and command tool names as shell invocations. The command string is extracted from the tool arguments and matched against a risk classifier:

Command pattern	Action	Risk
`rm -rf` / `rm -r` / `rm --recursive`	`file.delete_recursive`	critical
`git push --force` / `git push -f`	`git.force_push`	critical
`DROP TABLE` / `DROP DATABASE` / `TRUNCATE`	`sql.destructive`	critical
`curl … \| bash` / `wget … \| sh`	`shell.remote_exec`	critical
`chmod 777`	`file.permission_change`	high
`sudo …`	`shell.sudo`	high
`docker rm` / `docker rmi`	`container.delete`	high
`kubectl delete`	`k8s.delete`	high
`git reset --hard`	`git.reset_hard`	high
`git push` (no force)	`git.push`	medium
`git branch -D`	`git.branch_delete`	medium
`ls`, `cat`, `grep`, `find`, `echo`, …	`shell.read`	low
Everything else	`unknown_write`	medium

MCP methods

Only the following JSON-RPC methods pass through to the upstream server:

initialize — handled locally; proxied to upstream if connected
tools/list — forwarded to upstream, results cached 60 seconds
tools/call — intercepted and policy-evaluated
ping — answered locally

All other methods (resources/*, prompts/*, custom methods) are denied with error code -32601. This prevents agents from routing side-effecting work around the policy engine.

Decision flow

allow

The call is forwarded to the upstream MCP server. The result is returned to the agent with no modification.

✅ ALLOW   bash · Read-only shell command

block

The upstream server is never contacted. The agent receives a JSON-RPC error:

{
  "error": {
    "code": -32000,
    "message": "🛑 Blocked by Sentrail: Destructive file deletion (rm -rf) blocked by Sentrail policy. Policy: Block destructive deletes"
  }
}

🛑 BLOCK   bash · Destructive file deletion (rm -rf) blocked by Sentrail policy

require_approval

The proxy holds the call and waits for a human decision:

Prints the pending notice to the terminal with the action details.
Sends an approval request to the Sentrail cloud (and notifies configured reviewers via Slack/email).
Polls the cloud for the decision every 3 seconds, up to 120 seconds (configurable).
On approve: forwards the call to upstream and returns the result.
On deny or timeout: returns a block error to the agent.

⏳ APPROVAL REQUIRED   bash · Force push to a protected branch (main/master/prod)

Fail-closed behavior

If the Sentrail cloud is unreachable (network error, timeout, 5xx), the proxy fails safe:

Write actions (medium/high/critical risk) → blocked
Read-only actions (low risk) → allowed through

This means a cloud outage does not allow destructive commands to slip through unchecked.

Running without an upstream server

The proxy starts and accepts connections even if no upstream MCP URL is configured. Allowed calls will return an error when forwarding is attempted. This is useful for testing policy behavior in isolation — blocks and approvals work correctly without an upstream.

​Architecture

​What gets intercepted

​Shell commands

​MCP methods

​Decision flow

​allow

​block

​require_approval

​Fail-closed behavior

​Running without an upstream server