AgentBound — Replication Package for MCP Security Framework This repository contains the replication package for AgentBound, a security framework for Model Context Protocol (MCP) servers. It bundles the datasets, helper tools, sandbox implementations, and demonstration scripts used to produce the results in the paper. This repository is available under DOI: 10.5281/zenodo.19468201 There are two main files: `servers.tar.gz` which contains the list of 300 MCP servers with code, and the source-repository which contains the used source code described below. Overview AgentBound studies how to constrain MCP servers with a principled permission model and enforce it via a runtime sandbox. This package provides: - The full set of MCP servers referenced in the paper (benign, malicious, and generated). - Helper tools used during data collection and manifest generation. - A sandbox implementation (Docker and Python parts) with example agents and benchmarks. - Documentation of the permission taxonomy and runtime permission model. Repository Structure - `helpers/`: Utilities used to build the dataset and artifacts. - `helpers/malicious-server-creator/` (Python): Creates “malicious-looking” MCP servers for testing (e.g., tool poisoning, supply‑chain scenarios). Entrypoint: `main.py`. Includes `pyproject.toml` for reproducible environments. - `helpers/manifest-creator-agent/` (Python): Automates MCP manifest creation and validation. Useful scripts: `create_manifest.py`, `batch_create_manifests.py`, `validate_manifest.py`, `batch_validate_manifest.py`. - `helpers/mcp-server-downloader/` (Node.js): Fetches, categorizes, and orders MCP servers from PulseMCP. Key scripts: `download.js`, `categorize.js`, `order.js`, `analyze.js`. - `mcp-servers/`: Servers used and/or referenced in the paper. - `mcp-servers/data/`: Collected metadata and lists, e.g. `servers.json`, `ordered-servers.json`, `top-servers.json`, `permission-list.json` (derived from PulseMCP data). - `mcp-servers/malicious-servers/`: Artificial malicious servers used for evaluation (e.g., `tool-poisoning/`, `supply-chain-attack/`). - `mcp-servers/mcp-security-artifact/`: The four servers from the MCP security artifact (`google-maps/`, `mcp-weather-server/`, `mcp_server_time/`, `wechat-mcp/`) and `results.md`. - `mcp-servers/published/`: Downloaded top 300 MCP servers from PulseMCP. This data is not in the repository, but adjacent to the repository in `servers.tar.gz` (DOI: 10.5281/zenodo.19468201 ). - `sandbox/`: Sandboxing implementations and benchmarks. - `sandbox/docker/`: Containerized sandbox (Dockerfiles and `entrypoint.sh`) for isolated MCP execution. - `sandbox/python/`: Python sandbox library for executing MCP servers with explicit runtime permissions; see `sandbox/python/README.md` for an example usage with `SandboxedMCPStdio`. - `sandbox/benchmark/`: Benchmark harnesses for startup time and runtime performance (`startup-time-measurement/`, `runtime-performance/`). - `sandbox-demo-agent/`: A minimal agent that exercises different execution modes against a local (malicious) MCP server. - `native.py`: No sandbox (host process). - `semi_native.py`: Sandboxed with limited, simulated filesystem access and specific egress. - `sandboxed.py`: Fully sandboxed with least‑privilege network egress only. - `scripts/`: General helper scripts. - `collect_server_manifests.js`: Utility to collect or update manifests across sources. - `github_issues.py`: GitHub helper for issues/labels used during curation. - Documentation - `permission-system.md`: The high‑level MCP permission taxonomy used by AgentBound (manifest‑declared capabilities). - `sandbox-runtime-permissions.md`: The concrete runtime permission model (FS mounts, env variables, network egress) enforced by the sandbox at execution time. Getting Started Prerequisites used across tools: - Python (project uses `uv` for running scripts; `pyproject.toml` files are provided in Python subprojects). - Node.js (for `helpers/mcp-server-downloader/` and some scripts). - Docker (for the Docker sandbox and related experiments). Quick checks and demos: - Run the demo agent in different isolation modes (from `sandbox-demo-agent/`): ```bash uv run native.py uv run semi_native.py uv run sandboxed.py ``` - Use the Python sandbox library in your agent (see `sandbox/python/README.md`): it shows how to declare a manifest, attach runtime permissions (e.g., `FSAccess`, network egress), and execute an MCP server with enforcement. Reproducing Key Artifacts - Server collection and curation: - Download and preprocess server lists from PulseMCP using `helpers/mcp-server-downloader/` (`download.js`, `categorize.js`, `order.js`, `analyze.js`), yielding `mcp-servers/data/*.json`. - Manifest generation and validation: - Generate and batch‑validate MCP manifests with `helpers/manifest-creator-agent/` via `create_manifest.py`, `batch_create_manifests.py`, and `validate_manifest.py`. - Malicious server construction: - Generate artificial malicious examples using `helpers/malicious-server-creator/` (`main.py`) for scenarios like tool poisoning or supply‑chain attacks. - Sandbox enforcement and benchmarks: - Execute demo server under `sandbox-demo-agent` (with OpenAI API Key provided). - Run benchmarks under `sandbox/benchmark/` (`startup-time-measurement/`, `runtime-performance/`). Where applicable, each subfolder includes its own README or usage comments. For exact package versions, consult the respective `pyproject.toml`, `uv.lock`, or `package.json`/`package-lock.json` files. Notes on Permissions - Manifest‑level permissions describe capability topics (e.g., filesystem read/write, env access, network client/server, peripherals). See `permission-system.md`. - At runtime, concrete permissions (e.g., "mount this path read‑only", "allow egress to api.example.com:443", "inject env NAME") must be both covered by the manifest and consented by the user. See `sandbox-runtime-permissions.md` for data types and enforcement points.