Inspiration
Model Context Protocol gives coding agents powerful access to files, shells, processes, and network tools. That power is useful, but a developer should not have to trust every tool request simply because it came from an agent.
I built ToolBastion to provide a narrow security gateway and evidence layer between an AI coding agent and a local MCP target. The goal was to make each mediated tool call explainable: what was requested, what policy decided, whether the target executed, and what evidence was retained.
What I learned
The most important lesson was that deterministic security controls must run before model judgment. Path traversal, secret-file access, shell injection, SSRF, capability violations, and trust changes should be blocked mechanically and cannot be overridden by a model.
I also learned that trustworthy evidence requires more than logging. Trust baselines must bind to the actual target artifact, including Docker digests or executable and dependency hashes. Receipts must only be marked final after durable file creation succeeds. Recorded fixture evidence must also be clearly separated from live runtime evidence.
GPT-5.6 is useful for genuinely ambiguous calls, but it should receive bounded, schema-validated context. The recorded demo fixture resolves deterministically without GPT; that is why its judge-token count is zero.
How I built it
ToolBastion is implemented as a TypeScript MCP proxy. It presents an MCP server to the agent and connects to one local stdio MCP target.
The system includes:
- Zod-validated configuration and protocol boundaries
- Filesystem capability contracts with containment and symlink protection
- URL, shell, Unicode, encoding, nesting, and output-injection detection
- Trust baselines bound to Docker digests or executable/build/dependency hashes
- Durable redacted receipts and tamper-evident audit chains
- Optional Docker target-process containment with network isolation
- Structured GPT-5.6 checks for ambiguous requests only
- A read-only dashboard for runtime and recorded evidence
- Property-based adversarial tests using fast-check
- Unit, integration, Docker, Playwright, evaluation, packaging, and release checks
Challenges
The hardest parts were handling filesystem edge cases safely across platforms, detecting symlink and containment escapes, tracking target artifact changes, and making failure behavior fail closed.
Docker behavior also differed between local Windows development and GitHub Actions. A preflight timeout had to be treated as an explicit unavailable-image failure instead of allowing the test contract to depend on one platform’s error wording.
Another challenge was presenting evidence honestly. The deployed dashboard is a read-only recorded snapshot, while the live enforcement proof runs locally through the proxy. Keeping those two evidence sources clearly labeled prevents the interface from making stronger claims than the underlying run supports.
Outcome
ToolBastion now demonstrates mediated MCP execution with deterministic policy enforcement, optional target containment, redacted audit evidence, and structured handling of ambiguous calls. The project is designed to make agent tool use easier to inspect, test, and govern.
Log in or sign up for Devpost to join the conversation.