MCP — Filesystem Server

Enforce Scopebound policies on agents using the Filesystem MCP server.

Install

pip install scopebound

Role template

The Filesystem adapter ships a pre-built role template. Create the role once — it configures allowed_tools, allowed_paths, and sets approval_required on write and delete operations by default.

from scopebound import ScopeboundSDK
from scopebound.adapters.mcp_filesystem import FilesystemMCPAdapter

sb = ScopeboundSDK(base_url="https://your-partner.api.scopebound.ai", api_key="sb-...")

# Create role using the pre-built template
role = FilesystemMCPAdapter.role_template(
    name="filesystem-agent",
    allowed_paths=["/data/reports/*", "/tmp/*"],   # glob patterns
    read_only=False,                                # set True to block write/delete entirely
    approval_required=["write_file", "delete_file"] # HITL on destructive ops
)
sb.create_role(**role)

Integration

from scopebound.adapters.mcp_filesystem import FilesystemMCPAdapter

adapter = FilesystemMCPAdapter(sb, role_id="filesystem-agent")

# Sync MCP server
@server.pre_call
def enforce(tool_name: str, arguments: dict) -> None:
    adapter.enforce(tool_name, arguments)

# Async MCP server
@server.pre_call
async def enforce(tool_name: str, arguments: dict) -> None:
    await adapter.async_enforce(tool_name, arguments)

Enforced tools

Tool	Default policy	Notes
read_file	Allow	Path must match allowed_paths
write_file	Approval required	Path must match allowed_paths
list_directory	Allow	Path must match allowed_paths
delete_file	Approval required	Path must match allowed_paths

Deny codes

Code	Trigger
SCOPE_VIOLATION	Tool not in role's allowed_tools
PARAMETER_VIOLATION	Path does not match any allowed_paths pattern
MCP_SERVER_UNAUTHORIZED	Agent's JWT does not include filesystem in allowed_mcp_servers
MCP_TOOL_NOT_FOUND	Tool name not in Filesystem MCP server's declared manifest
MCP_ARGUMENT_SCHEMA_VIOLATION	Required argument (path) missing from call

HITL approval flow

When write_file or delete_file is called, Scopebound returns HTTP 202 and pauses execution. The agent polls for approval:

from scopebound import ScopeboundPendingError

try:
    adapter.enforce("write_file", {"path": "/data/reports/q1.csv", "content": "..."})
except ScopeboundPendingError as e:
    # Poll until approved or TTL expires
    while True:
        status = sb.get_approval(e.approval_id)
        if status["status"] == "approved":
            break
        if status["status"] in ("rejected", "expired"):
            raise PermissionError("Write not approved")
        time.sleep(2)

Direct endpoint

curl -X POST https://your-partner.api.scopebound.ai/v1/mcp/enforce \
  -H "X-Scopebound-API-Key: sb-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "jwt": "your-session-jwt",
    "tool_name": "read_file",
    "arguments": {"path": "/data/reports/q1.csv"},
    "mcp_server": "filesystem",
    "mcp_tool_schema": {"required": ["path"]}
  }'