Skip to main content

MCP gating (mcp-proxy)

belay mcp-proxy wraps any MCP (Model Context Protocol) server so that every tools/call request passing through it is gated by Belay's deterministic engine — not just the agent's built-in tools. It speaks MCP over stdio on both sides, so it drops in transparently between an agent and the real server.

When to use​

  • Any agent that reaches tools through an MCP server (for example editor-embedded agents like Cline, Roo, Cursor, OpenClaw, and Hermes).
  • Any standalone MCP server you want to put behind the policy boundary — a filesystem server, a shell/exec server, a database server, and so on.
  • Anywhere you need tools/call requests inspected and blocked, not merely logged.

How it works​

mcp-proxy launches the real MCP server as a child process and sits in the middle of the stdio stream. Each tools/call request is intercepted and evaluated against the rule catalog before it is forwarded:

  • allow → the call is passed through to the real server unchanged.
  • ask → the call pauses for a human Allow / Deny decision.
  • deny → the call is rejected and never reaches the real server.
Fail-closed

A headless proxy denies anything that is not an explicit allow. An ask with no answer, or any error in the pipeline, becomes a deny. This is intentional: the safe default is to block.

Steps​

1. Wrap the server​

Put belay mcp-proxy -- in front of the command you would normally use to start the MCP server. Everything after -- is the real server command and its arguments:

belay mcp-proxy -- <server-command> [args...]

For example, wrapping a hypothetical filesystem MCP server:

belay mcp-proxy -- mcp-server-filesystem /home/project

2. Point the agent at the proxy​

In the agent's MCP configuration, replace the direct server command with the wrapped one. Concretely, an entry that used to launch the server directly:

{
  "command": "mcp-server-filesystem",
  "args": ["/home/project"]
}

becomes a call through the proxy:

{
  "command": "belay",
  "args": ["mcp-proxy", "--", "mcp-server-filesystem", "/home/project"]
}
tip

For the agents in the detect table whose interception method is mcp-proxy, running belay protect <agent> performs this config rewrite for you.

3. Verify calls are being gated​

Run the agent normally and watch the audit log — every gated tools/call produces a row:

belay logs -n 50

Notes​

  • The proxy adds a policy check to the MCP request path; it does not change the MCP protocol the agent or server speak.
  • Verdicts follow the same precedence as everywhere else in Belay: Deny > Ask > Allow, and a deny can never be downgraded by the dev-toolchain allowlist.
  • An ask verdict here can be answered inline in the terminal, in the Desktop App, or routed to a chat channel for a two-way Allow / Deny reply — see Notifications & channels.