Blackwall MCP

What bluetieroperations-create/blackwall-mcp MCP server does

bluetieroperations-create/blackwall-mcp MCP server places a risk check before actions that may be difficult to undo. An agent submits an action type and its concrete inputs to forecast; examples include sending an email, making a payment, running SQL, deleting a file, posting content, or calling a state-changing external API.

The response includes a risk score from 0 to 100, a reversibility class and rollback cost, a recommendation of GO, CAUTION, or STOP, and a corresponding gate such as proceed, confirm, or human-required. It also reports confidence, named red flags, a predicted result, alternative actions, and a receipt. The README describes 28 failure modes used for the named red flags.

How it works

The normal workflow is to call forecast before the side effect. A GO result can proceed, while CAUTION requires confirmation and STOP should prevent the action and expose the flags to the user. The tool supports standard and deep analysis depths, with standard as the default, and accepts optional context such as the agent role, user intent, and environment.

After the action runs, call observe with the original forecast identifier. It can also report that an action was not run because the forecast returned STOP or HUMAN_REQUIRED. Outcomes include matched, over_scope, under_scope, no_op, diverged, and aborted, with optional divergence severity and details. The README states that observation is free and does not consume tokens.

For JavaScript or TypeScript agents, the package also exports a gate() control and lower-level forecast and observe functions. gate() wraps an action, applies the verdict, and reports the outcome automatically. It fails closed when a verdict is unavailable unless failOpen: true is explicitly supplied; an optional onCaution callback can handle confirmation.

Setup and configuration

The server requires a BlackWall API key obtained from the BlackWall dashboard. Install and run it with npx -y blackwall-mcp, then provide BLACKWALL_API_KEY in the MCP host environment. The README gives configurations for Claude Desktop and Cursor, and states that it works with Claude Code, Windsurf, and MCP-compatible agent frameworks.

BLACKWALL_BASE_URL optionally changes the default service URL, which is https://blackwalltier.com. BLACKWALL_MODE defaults to enforce; setting it to observe logs and scores actions without instructing the agent to stop them. The documented free tier provides approximately 100 forecasts per month without requiring a card.

Tools and capabilities

• forecast: evaluates a proposed action and returns its risk and gate decision.
• observe: records the actual result against a previous forecast.
• Decision receipts: forecast responses include a receipt containing signatures over hashes of the request and response, which can be verified offline with the published key.
• JavaScript/TypeScript library access: use gate(), forecast, and observe without an MCP host.

Limitations and notes

The server depends on an API key and a reachable BlackWall service unless the library call can otherwise obtain a verdict. The default enforcement behavior can block actions with STOP, unconfirmed CAUTION, or unavailable forecasts when using gate(). Observe mode does not block actions, so it is suitable for recording what would have been stopped rather than enforcing a gate.

The README says free-tier receipt retention is 90 days and paid retention is indefinite. Forecasts are described as taking roughly four to eight seconds. The MCP tools provide a decision and supporting information; they do not execute the underlying email, payment, database, file, or publishing action themselves.