Trentina

Trentina is a secure MCP gateway that inspects everything between your AI agents and the outside world — web content, MCP tool responses and tool definitions, Matrix messages, LLM completions, and monitoring alerts — through a three-layer defense pipeline at every ingress, with per-profile enforcement (flag or block) and a full audit trail. Content is never silently modified: what your agent reads is what actually arrived, plus Trentina's verdict. (E2EE Matrix rooms are ciphertext at the gateway and outside what any proxy can defend.) Named after the 1377 quarantine system from Ragusa, where incoming ships had to anchor offshore for thirty days before anyone was allowed into the city. Same idea: keep the commerce flowing without letting something dangerous through.

Capabilities

MCP Gateway

Single chokepoint between your agents and all their MCP backends. One endpoint, one bearer token, one audit log — instead of each agent connecting directly to dozens of MCP servers. Backend tools are namespaced automatically (slack__slack_search_messages, github__list_issues_tool) so there are no collisions.

Authentication

Four ways a client can prove who it is, chosen per profile: a static bearer token, an OAuth identity Trentina issues while proxying login to Google (with dynamic client registration or a provisioned confidential client), or a token minted by an external identity provider that Trentina only verifies — for connectors that will not authenticate against a third-party authorization server.

Per-Agent Profiles

Each consumer — Claude Code, Hermes, OpenClaw, or any MCP client — gets its own profile with independent tool access, defense settings, and authentication. Your human-supervised agent can have full tool access while your autonomous agent gets a locked-down subset, all through the same gateway.

Tool Allowlists & Denylists

Control which tools each agent can even see. Tools not in the allowlist are stripped from tools/list responses before they reach the consumer — they never enter the agent's context window. Supports exact names and glob patterns (delete*, *_gmail_*). Reduces both context cost and attack surface.

Parameter Guards

Per-tool argument validation at the gateway level. Restrict what values an agent can pass, not just which tools it can call. Example: "this agent can send email, but only to user@example.com." The call is rejected before it reaches the backend — no tokens spent, no side effects. Deterministic enforcement that doesn't depend on LLM behavior.

Response Guards

The egress half of parameter guards: the same allow/deny constraint applied to what a backend returns, before the result is reduced, scanned or relayed. Argument-side matching cannot cover a semantic tool — an agent asking a memory server for "my employer's roadmap" sends nothing matchable, and the restricted material arrives in the response. Deny-oriented, blocks the whole response rather than scrubbing it, and audited as policy rather than failure.

Three-Layer Defense Pipeline

Every piece of untrusted content passes through three independent detection layers. Layer 1 deterministically detects structural attacks (hidden markup, invisible Unicode, encoded payloads, exfiltration URLs) and normalizes a copy for Layer 2 to read. Layer 2 runs a Prompt Guard 2 86M classifier on that copy to catch instruction overrides. Layer 3 hands the original content to a quarantined LLM (Gemini Flash Lite) for semantic analysis — no tools, no memory, minimal blast radius. Each layer catches what the others miss.

Tool Description Compression

MCP servers ship verbose tool descriptions that waste context tokens. Trentina uses an LLM to compress every tool description as it passes through the gateway, caching results in SQLite so the model is only called once per unique description. Real-world results: 154 tools compressed from 62K to 17K characters (72% reduction), saving ~11K tokens per session. The compressed descriptions are fully functional — agents use them without issue.

Gateway Audit Log

Every tool call through the gateway is recorded in SQLite with profile, backend, tool name, success/failure, duration, and error message. The quarantine_stats tool exposes this data for monitoring — tool call counts, error rates, per-backend breakdowns. Data-driven evidence for tightening allowlists and identifying problems.

Cumulative Detection Memory

When block refuses a source, Trentina records it in a SQLite blocklist, and later block/flag requests for it are refused before anything is fetched — the system remembers what it's seen before. Blocklist entries include the source URL or content hash, detection timestamp, and risk level.

Content Tools

Five tools — fetch (URL), read (file), dir (directory listing), content (inline text), search (web) — each taking a trentina_mode argument. Every call runs all three layers; the mode decides only what is delivered. block refuses flagged or incompletely judged content. flag delivers the exact bytes with the verdict attached — a security-researcher grant. redact returns an extraction that L3 wrote and a second L3 pass verified, guided by trentina_prompt. The names are OpenRouter's guardrail actions, though redact rewrites through L3 rather than substituting spans; warn and clean, the pre-0.35.0 names, are deprecated aliases. Which modes an agent may choose is policy, not the agent's call: the profile's defense.modes through the gateway, which inserts the same argument into every backend's tools, or TRENTINA_MODE/TRENTINA_MODES standalone.

LLM Key Proxying

Proxy LLM API calls (Gemini, OpenAI, Anthropic) through the gateway so API keys never leave the trusted boundary. Agents send model requests to Trentina, which forwards them with the real credentials. Adding a new provider is a YAML entry, not code. Streaming and non-streaming responses are forwarded transparently.

Matrix Reverse Proxy

Proxy Matrix Client-Server API traffic through the gateway so agents on the internal network can communicate via Matrix without direct internet access. Agents point MATRIX_HOMESERVER at Trentina instead of matrix.org. Long-poll /sync timeouts are tuned automatically.

Cockpit Plugin

Live web dashboard for the defense pipeline, built as a Cockpit plugin with PatternFly 6. Shows layer status, blocklist entries, and pipeline events in real time through the same web console sysadmins already use to manage RHEL systems. Vanilla JavaScript, no React, no build step.

Quick Start

# PyPI
pip install mcp-trentina-crunchtools

# uvx (zero-install)
uvx mcp-trentina-crunchtools

# Container (includes Prompt Guard 2 86M classifier)
podman run quay.io/crunchtools/mcp-trentina

Minimal Configuration

# Required for Layer 3 (Q-Agent) and description compression
export GEMINI_API_KEY=your-key

# Enable gateway mode
export TRENTINA_GATEWAY_ENABLED=true
export TRENTINA_PROFILES_PATH=/path/to/profiles.yaml

# Per-profile bearer tokens
export TRENTINA_PROFILE_MYAGENT_TOKEN=your-token

Claude Code

{
  "mcpServers": {
    "trentina": {
      "type": "streamable-http",
      "url": "http://localhost:8019/gateway/myprofile/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Documentation

Environment Variables

Trentina reads its gateway, profile and backend configuration from a YAML file; these variables control the process itself. Profile tokens (TRENTINA_PROFILE_<NAME>_TOKEN) and provider API keys are covered in Per-Agent Profiles and LLM Key Proxying.

Development

uv sync --all-extras
uv run ruff check src tests
uv run mypy src
uv run pytest -v

The container image is built by the GHA pipeline (container.yml), never locally. The model-export stage needs a gated HuggingFace credential that only CI holds, and building outside the pipeline causes drift. Push the branch and let the pipeline verify the image.

License

AGPL-3.0-or-later