GCF Proxy
blackwell-systemsLABSCO SUMMARY
It fixes a gap the protocol leaves open.
MCP has no resilience layer of its own, so a single unresponsive upstream can stall an agent for as long as the client is willing to wait. Putting the retry and breaker policy in a proxy means it applies to servers you do not control and did not write. The per-tool config is where it earns its place — a search call and a file read rarely deserve the same timeout.
What it is
A transparent stdio proxy that sits between your agent and another MCP server. You launch the target server through it instead of directly, and every tool call inherits a timeout, a retry policy, a circuit breaker and structured logging.
What you get
- A hard timeout on every tool call, so a hung upstream API stops blocking the agent
- Retries with exponential backoff and jitter — deterministic errors such as invalid params or method not found are never retried
- A circuit breaker that trips after repeated failures and moves through Closed, Open and Half-Open rather than hammering a dead server
- One structured JSON line per call on stderr, carrying the server, the tool,
duration_ms, status and attempt number - Per-tool overrides in a YAML config: a slow tool gets a longer timeout, a flaky one gets more retries
- A programmatic entry point,
shield({...}), for wiring the same proxy into your own code
Requirements
Node.js 20 or newer and the npm package @daino/mcp-shield, version 1.1.0, installed globally or run through npx. Usage is mcp-shield wrap -- <the server command>; the defaults are a 30s timeout and 2 retries, overridable with --timeout and --retries or a --config file. In a client config, it replaces the server's own command line and keeps the target server's environment variables.
Setup effort
One command — npm install -g @daino/mcp-shield
USE CASES
01
Stopping a hung API from freezing an agent
Cap each tool call so a slow upstream returns an error instead of holding the conversation open.
02
Riding out transient network failures
Retry with backoff on the errors worth retrying, and skip the ones that will fail identically every time.
03
Backing off from a server that is down
After repeated failures the breaker opens and calls fail fast, instead of spending tokens on a dead endpoint.
04
Seeing which tool is actually slow
Every call is logged as JSON with its duration and outcome, so the slow one is a grep away.
BEFORE YOU INSTALL
What to know first
Requires
npx on PATH
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
npm install -g @daino/mcp-shieldMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"@daino/mcp-shield",
"wrap",
"--timeout",
"30s",
"--retries",
"3",
"--",
"npx",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>"
}
}
}
}
