saurabh-yergattikar/shieldmcp

ShieldMCP sits between an agent and its MCP server, checking tool metadata, outbound arguments, and inbound responses through one inspectable pipeline. Deploy it as a transparent stdio or legacy SSE proxy, or integrate its asynchronous Python API.

Apache-2.0 licensed code and released model artifacts, including commercial use and integration under the same license. The default detector runs locally without model downloads or API keys.

Research papers

A* refers to the conference venues’ ICORE2026 rankings: ACL, EMNLP. The EMNLP paper appears as 69-DEMO in the official presentation schedule; its Anthology link will be added when available.

Features

The distinctive design combines metadata integrity, call validation, and response analysis at the MCP boundary, with local detection and reproducible inspection. This is an alpha research framework; test the configured controls against your own agents, tools, and workloads. Experimental governance/cache APIs require explicit integration and are not enabled by the default CLI proxy.

Quick start

git clone https://github.com/saurabh-yergattikar/ShieldMCP.git
cd ShieldMCP
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Interactive pipeline demo: http://127.0.0.1:8000
shieldmcp demo

The default heuristic backend needs no model downloads or API keys. The browser demo computes pipeline verdicts live against curated scenarios and user inputs; it is not a live agent benchmark. For subprocess traffic through the actual stdio proxy:

python examples/live_proxy_demo.py

For an independent review, start with the red-team guide, model setup and limitations, and the framework evaluation.

Architecture

Agent --tools/list--> [Stage 1: metadata integrity] --> MCP server
Agent --tools/call--> [Stage 2: argument checks]    --> MCP server
Agent <--response--- [Stage 3: response analysis]  <-- MCP server

Detection is heuristic or model-based, with false positives and false negatives. Stage 3 runs after a tool executes: it can withhold a response, but cannot undo a side effect. Parameter checks do not replace application authorization or a general execution sandbox.

Proxy and configuration

shieldmcp init
shieldmcp scan examples/tools.json
shieldmcp proxy --server-id my-server -- python your_mcp_server.py
shieldmcp registry

# Legacy HTTP/SSE transport
shieldmcp sse-proxy --backend-url http://127.0.0.1:3000

The stdio proxy accepts newline-delimited JSON-RPC and Content-Length framing. Legacy SSE support is separate; Streamable HTTP is not implemented. See default configuration.

stage1:
  semantic_backend: heuristic  # heuristic | llm_judge | classifier | tiered
  semantic_threshold: 0.72
  tiered_band_low: 0.12
stage3:
  instruction_detection_backend: heuristic  # heuristic | classifier | tiered
  tiered_min_words: 20

classifier uses local fine-tuned DistilBERT detectors. tiered routes selected ambiguous inputs through those classifiers after inexpensive heuristic checks. Download the trained artifacts or train locally using model setup. The stage wrappers log a heuristic fallback if models/dependencies cannot load; confirm the models are loaded before treating a run as classifier evaluation. The llm_judge Stage 1 backend requires external model access.

Python API

import asyncio
from shieldmcp.core.config import ShieldMCPConfig
from shieldmcp.core.pipeline import ShieldPipeline

async def main():
    pipeline = ShieldPipeline(ShieldMCPConfig())
    await pipeline.initialize()
    try:
        action, tools, alerts = await pipeline.validate_tools("docs", [{
            "name": "read_page",
            "description": "Return the text of a document.",
            "inputSchema": {"type": "object", "properties": {
                "id": {"type": "string"}}, "required": ["id"]},
        }])
        action, alerts = await pipeline.process_tool_call(
            "docs", "read_page", {"id": "guide"}, session_id="review")
        action, content, alerts = await pipeline.process_tool_response(
            "docs", "read_page", "Document contents", session_id="review")
    finally:
        await pipeline.shutdown()

asyncio.run(main())

Integrators must honor returned actions before executing a call or giving content to an agent. The command-line proxy does this automatically.

Experimental governance APIs

PolicyEnforcedPipeline adds explicit failure policies, task-scoped tool exposure, and schema pinning. GovernedResponseCache implements validated response caching with an eligibility predicate. These are opt-in Python APIs with synthetic benchmarks; they are not wired into the default CLI proxy. Integrators must provide the policy-aware wrapper and cache lifecycle themselves.

Evaluation and development

pip install -e '.[all]'
pytest -q

# Framework detection evaluation: 487 attack + 200 benign scenarios
python eval/run_evaluation.py --framework-only --output-dir /tmp/shieldmcp-heuristic-review

# Requires trained artifacts; use separate output directories
python eval/run_evaluation.py --framework-only --backend classifier --output-dir /tmp/shieldmcp-classifier-review
python eval/run_evaluation.py --framework-only --backend tiered --output-dir /tmp/shieldmcp-tiered-review

python eval/benchmarks/latency_benchmark.py --iterations 1000

The framework harness measures detection on fixed synthetic scenarios. Its historical default result (8.6% attacks not detected; 95% benign pass) is not a live-agent exploit rate. Classifier validation and benchmark results are within-distribution; independent paraphrased, multilingual, encoded, long-context, and adaptive attacks remain important. Raw evaluation outputs and training scripts are included for inspection.

workshop/agent_console.py uses a local Ollama model with simulated page/email tools; blocked content is replaced with a known clean demo page. examples/trust_issues_ui.py animates a scripted conversation with a real Stage 3 verdict. Neither sends email. Use examples/live_proxy_demo.py for actual subprocess proxy traffic.

The system demonstration paper describes the research context. HANDOFF.md records implementation status and verification boundaries.

Citation

If ShieldMCP supports your work, please cite the published ACL paper. The EMNLP System Demonstrations paper is linked above; an official proceedings citation will be added with its Anthology entry.

@inproceedings{yergattikar-2026-securing,
  title = "Securing the Tool Layer: A Threat Taxonomy and Runtime Defense Framework for Model Context Protocol Deployments",
  author = "Yergattikar, Saurabh",
  booktitle = "Proceedings of the 64th Annual Meeting of the Association for Computational Linguistics (Volume 6: Industry Track)",
  year = "2026",
  pages = "865--871",
  publisher = "Association for Computational Linguistics",
  doi = "10.18653/v1/2026.acl-industry.58",
  url = "https://aclanthology.org/2026.acl-industry.58/"
}

License

Apache-2.0 covers ShieldMCP code and released classifier artifacts for research and commercial integration. No separate ShieldMCP license fee is required; retain the applicable license and attribution notices. The fine-tuned classifiers derive from the Apache-2.0 DistilBERT base model; see model provenance.