Agentrim MCP

A least-privilege enforcement proxy for MCP servers.

Agentrim MCP sits between an MCP client (an agent or LLM harness) and one or more real upstream Model Context Protocol servers. It builds and verifies a tool inventory offline, then enforces least-privilege access to that inventory online: hiding denied tools entirely, requiring human confirmation for risky ones, validating every call against parameter constraints and rate limits, and logging everything in a structured, greppable audit trail.

Table of contents

• How it works, in plain English
• Architecture
• Provenance
• Quickstart
• Installing
• Command-line reference
• Writing a policy
• Running in production
• Testing
• Evaluation
• Security
• Troubleshooting
• Known issues and roadmap
• Contributing
• License

How it works, in plain English

Think of an AI agent as a traveler, and the tools it can call (delete a file, send an email, read a spreadsheet) as items the traveler wants to carry onto a plane. agentrim-mcp is the security checkpoint standing between the traveler and the gate.

• Before anyone travels, security studies the manifest. The offline extractor connects to the real server once, reads the full list of tools it offers, and writes down what each one does and how risky it looks (read-only, like reading a book, versus destructive, like detonating something). If a tool's description quietly changes later, that is flagged immediately: a tool that used to say "reads a file" suddenly saying "reads a file and emails it to a stranger" is exactly the kind of trick a hidden attacker would try, and it gets caught before anyone acts on it.
• At the gate, the traveler only sees the lanes they are allowed to use. Tools that are outright forbidden never even show up in the list the agent sees. An agent cannot be tricked into asking for something it never knew existed.
• Every attempt to use something is checked, every single time. An everyday, harmless action passes straight through. A risky action gets held for a human to approve first. A dangerous action is stopped automatically, no matter how the request is worded or how convincing the surrounding conversation sounds.
• Everything is written in a logbook. Every decision, allowed, denied, or held for approval, is recorded, so if something ever goes wrong there is a full paper trail to investigate.

That is the entire idea. The rest of this document is the engineering detail behind those four bullet points.

Architecture

flowchart TB
    subgraph Offline["Offline: run once per upstream server"]
        direction LR
        SA[static_analyzer.py] --> TC[trace_collector.py]
        TC --> RC[risk classifier]
        RC --> V[verifier.py]
    end

    V --> INV[(ToolInventory JSON<br/>drift-checked)]

    subgraph Online["Online: every agent request"]
        direction LR
        AF[adaptive_filter.py]
        VA[validator.py]
    end

    Agent["Agent / LLM<br/>MCP client"] <-->|MCP| PS[proxy_server.py]
    PS --> AF
    PS --> VA
    INV --> AF
    INV --> VA
    PS <-->|MCP| Upstream["Real upstream MCP server<br/>filesystem, memory, ..."]
    PS --> AL[audit_log.py<br/>JSON lines]

A single tool call looks like this:

sequenceDiagram
    participant Agent as Agent / LLM
    participant Proxy as agentrim-mcp
    participant Policy as Policy engine
    participant Upstream as Real MCP server

    Agent->>Proxy: tools/call delete_file
    Proxy->>Policy: evaluate(tool, arguments)
    Policy-->>Proxy: DENY, destructive tier
    Proxy-->>Agent: DENIED, with reason
    Note over Proxy,Upstream: Upstream is never contacted

Full design detail, including every judgment call made and why, is in docs/architecture.md.

Provenance, please read this

This is an independent engineering interpretation of the two-phase architecture (offline tool extractor plus online tool orchestrator enforcing least-privilege tool access via adaptive filtering and status-aware validation, evaluated on AgentDojo) described in AgenTRIM (arXiv:2601.12449, Betser, Bose, Giloni, Picardi, Padakandla and Vainshtein, Fujitsu Research, submitted January 2026, under review). The paper discloses that architecture at a conceptual level but not its exact algorithms, thresholds, or scoring functions, and this project does not claim to reproduce any of that. Every design decision that goes beyond what the paper discloses (the risk classifier's keyword heuristics, the policy YAML schema, the relevance-ranking algorithm, the sequence-anomaly enforcement strength, and more) is original engineering work, tracked claim by claim in docs/paper-mapping.md.

This repository was also built and tested inside a sandboxed environment with no live LLM API access. Every result described as "real" below (extraction against live servers, test pass counts, evaluation numbers) was actually run during development; see PROGRESS.md for the phase-by-phase log and KNOWN_ISSUES.md for the real bugs live testing surfaced. The shipped evaluation numbers are an explicitly-labeled illustrative synthetic run, not a live AgentDojo benchmark against an LLM; see Evaluation below.

Quickstart

git clone <this-repo> agentrim-mcp && cd agentrim-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 1. Cache the official filesystem MCP reference server once (needs npm registry access).
npx -y @modelcontextprotocol/server-filesystem --help

# 2. Find its resolved entrypoint. Invoking node directly avoids a real npx
#    stdio-interaction bug documented in KNOWN_ISSUES.md #1.
ENTRYPOINT=$(find "$(npm config get cache)/_npx" -path "*server-filesystem/dist/index.js" | head -1)

# 3. Extract and verify a tool inventory for a sandbox directory.
mkdir -p /tmp/agentrim-sandbox
agentrim extract --server-name filesystem --command node \
    --args "$ENTRYPOINT /tmp/agentrim-sandbox" \
    --output /tmp/fs_inventory.json
agentrim verify /tmp/fs_inventory.json

# 4. Serve the proxy in front of the real server.
agentrim serve --inventory-path /tmp/fs_inventory.json \
    --policy-path src/agentrim/policy/default_policy.yaml \
    --upstream-command node \
    --upstream-args "$ENTRYPOINT /tmp/agentrim-sandbox" \
    --audit-log-path /tmp/agentrim_audit.jsonl

Point your MCP client's stdio transport at agentrim serve (instead of directly at the upstream server) and it now enforces the policy in default_policy.yaml: read-only tools allowed, writes require confirmation through the agentrim_confirm meta-tool, destructive or unclassified tools denied. See examples/wrap_filesystem_server.py and examples/wrap_memory_server.py for runnable, end-to-end programmatic versions of the same flow; both were run live against the real reference servers during development.

Every step above completes in well under five minutes on a machine with npm registry access. The only slow step is the one-time package cache warm (roughly 10 to 20 seconds); everything after is near instant.

Installing

pip install -e ".[dev]"     # core package plus test and lint tooling
pip install -e ".[eval]"    # adds agentdojo, for the evaluation harness

Requirements:

• Python 3.10 or newer.
• agentrim serve/extract launch upstream MCP servers as subprocesses (for example via node, npx, or any other command), so whatever runtime the upstream server needs (Node.js, Go, and so on) must also be installed separately. Most official MCP reference servers need Node.js 18 or newer.

Docker

A Dockerfile is included for containerized deployment:

docker build -t agentrim-mcp .
docker run --rm -it \
    -v "$(pwd)/data:/data" \
    -v "$(pwd)/logs:/var/log/agentrim" \
    agentrim-mcp \
    agentrim serve \
      --inventory-path /data/inventory.json \
      --policy-path /app/config/example.policy.yaml \
      --upstream-command node \
      --upstream-args "/data/upstream-server/index.js /data" \
      --audit-log-path /var/log/agentrim/audit.jsonl

Note: the Dockerfile has been reviewed for correctness but has not been build-tested in this project's own development environment, since Docker was not available there. Please verify it builds in yours before relying on it; see KNOWN_ISSUES.md for the full note.

Command-line reference

All commands are available via the agentrim entrypoint once installed.

agentrim extract

Connects to a live upstream MCP server, runs the offline extractor, and writes a verified tool inventory.

Flag	Required	Description
--server-name	yes	Logical name for the upstream server, stored in the inventory.
--command	yes	Command used to launch the upstream server, for example node.
--args	no	Space-separated arguments for that command.
--trace-file	no	Path to a JSONL execution-trace log to augment the inventory with observed call sequences.
--output	no	Path to write the inventory JSON (default inventory.json). If a file already exists there, it is used as the previous inventory for drift detection.

agentrim verify

agentrim verify path/to/inventory.json

Prints a table of every tool in a previously extracted inventory, its risk tier, and whether it is currently flagged for description or schema drift.

agentrim serve

Starts the orchestrator proxy: connects to the real upstream server over stdio and serves a filtered, validated MCP server over stdio to the downstream client.

Flag	Required	Description
--inventory-path	yes	Path to a verified inventory JSON (from extract).
--policy-path	yes	Path to a policy YAML file.
--upstream-command	yes	Command used to launch the upstream server.
--upstream-args	no	Space-separated arguments for that command.
--max-visible-tools	no	Cap on how many tools are shown per tools/list after relevance ranking.
--audit-log-path	no	Path to write JSON audit log lines; if omitted, logs go to stdout.

agentrim report

agentrim report path/to/audit.jsonl

Summarizes an audit log: total validated calls, counts by verdict, drift-related denials, and how many soft sequence anomalies were logged.

Writing a policy

Policies are explicit, human-editable YAML with a structurally-enforced default-deny posture: Policy.default_action cannot be set to allow, the schema itself raises on load if you try. See src/agentrim/policy/default_policy.yaml for the minimal default this repo ships with, and config/example.policy.yaml for a fuller, annotated example covering parameter constraints, rate limits, and glob rules, including a documented pitfall around rule ordering.

Minimal shape:

version: 1
default_action: deny   # only "deny" or "confirm" are ever valid here

risk_tier_defaults:
  read_only: allow
  write: confirm
  destructive: deny
  unknown: deny

rules:
  - tool: "read_file"
    action: allow
    param_constraints:
      - param: "path"
        deny_patterns: ["\\.\\."]   # blocks path traversal, checked against
                                     # both the raw and URL-decoded value

global_rate_limit_per_minute: 120

Running in production

A few practical notes beyond the Quickstart:

• Run agentrim extract on a schedule (a cron job or CI job) against your production upstream servers, and diff the resulting inventory against the previous one before deploying it; agentrim verify and the drifted column it prints are the signal to look at.
• Point --audit-log-path at a durable, rotated log destination. The audit logger writes one JSON object per line, so it is directly consumable by jq, a log shipper, or agentrim report.
• Treat the policy YAML as configuration that goes through the same review process as code; it is the actual security boundary.
• The proxy currently tracks one logical session per process (see docs/architecture.md's Roadmap for a future multi-session store), so run one agentrim serve process per agent connection in a multi-agent deployment.

Testing

pytest -v --cov=agentrim --cov-report=term-missing
ruff check src/ tests/ evaluation/ examples/
ruff format --check src/ tests/ evaluation/ examples/
mypy src/

86 tests, all passing, at roughly 93 percent statement coverage on src/agentrim as of the last run; ruff and mypy --strict are both clean. Coverage is weakest in cli.py (around 76 percent), mostly the serve command's live-process wiring, which is exercised by the example scripts run manually rather than by unit tests. tests/test_stress.py covers scale (2000-tool inventories, 10,000-line trace files), unicode tool names and arguments, exact rate-limit boundaries, and a range of malformed policy documents.

One CLI test and both examples/ scripts run live against the real, official @modelcontextprotocol/server-filesystem and @modelcontextprotocol/server-memory reference servers when node and those packages are available locally; they skip gracefully otherwise, so no network access is required to run the rest of the suite.

Evaluation

evaluation/agentdojo_runner.py is a real, tested integration with the actual AgentDojo package (agentdojo==0.1.35): it converts a real AgentDojo task suite's tools into an agentrim-mcp ToolInventory and wraps FunctionsRuntime so every call is validated by the same policy engine the MCP proxy uses.

evaluation/baseline_vs_agentrim.py, run for real during development, loads the actual official AgentDojo v1.1.1 workspace suite and its real environment, and runs a small, deterministic, non-LLM mock agent through three synthetic indirect-prompt-injection scenarios, with and without agentrim-mcp in front. This development environment has no live LLM API access, so this is explicitly an illustrative synthetic run, not a live AgentDojo benchmark; see the label in its own JSON output and docs/paper-mapping.md for why. The real result of that real run:

	Task Completion Rate	Attack Success Rate
Baseline, no agentrim-mcp	1.00	1.00
With agentrim-mcp	1.00	0.00

That is, the legitimate task still completes, and every injected-destructive-call attempt this scenario set models is blocked. Full output is in evaluation/results/illustrative_baseline_vs_agentrim.json. .github/workflows/eval.yml is ready for a maintainer with real LLM API credentials to run an actual AgentDojo benchmark.

Security

See SECURITY_REVIEW.md for an adversarial review that found and fixed a real path-traversal-encoding bypass, a real confirmation-token replay gap, and hardened the validator to fail closed on unexpected internal errors, all verified with tests rather than reasoned about in the abstract. This is a portfolio and reference project rather than a monitored production service; see CONTRIBUTING.md for how to report a further finding.

Troubleshooting

• npx-launched upstream servers crash or hang. Invoke node directly on the resolved entrypoint instead of going through npx; see KNOWN_ISSUES.md #1 for the root cause.
• A read-only-looking tool got classified as write or destructive. The risk classifier is a transparent keyword heuristic, not a semantic model; check src/agentrim/risk/risk_tags.py for the exact keyword lists and override the classification with an explicit rule in your policy YAML if needed.
• A tool I expected to be visible is missing from tools/list. Check whether it resolved to deny under your policy (denied tools are removed from the list entirely by design, not merely blocked at call time); agentrim verify and the audit log will show the policy decision.
• A confirmation token stopped working. Tokens expire after ProxyConfig.confirmation_ttl_seconds (300 seconds by default); request the call again to get a fresh token.

Known issues and roadmap

See KNOWN_ISSUES.md for real bugs found and fixed during development, including risk-classifier false positives found by running against live reference servers and AgentDojo's real tool set, and docs/architecture.md's Roadmap section for what was deliberately deferred rather than gold-plated for v1: semantic relevance ranking, a distributed session store, and a review dashboard.

Contributing

See CONTRIBUTING.md for setup instructions, the pre-commit hooks, and the standard this project holds itself to for new changes.

License

MIT, see LICENSE. Chosen for maximum compatibility with the MCP Python SDK and the broader MCP server ecosystem this project wraps, and because a permissive license suits a reference and portfolio security tool meant to be freely adapted.