"Whatever you see anywhere (sky, sea, clouds, lands) are all closed and opened by my hand." Ovid, Fasti I, 117–18 (Janus speaking)

JanuScope is the local MCP policy proxy. One YAML wraps any MCP server with policy, redaction, audit, and database-schema injection. Your tool traffic never leaves your machine.

JanuScope hides the dangerous tools, scrubs PII out of returned values before the model reads them, logs every call, and pre-injects your DB schema so the model doesn't waste five calls discovering it. Runs locally, no hosted gateway in the data path.

One YAML (called a Lens) wraps any MCP server with security guardrails, schema injection, and full audit logging. There are 20 bundled Lenses covering databases (Postgres, MySQL, MongoDB, ClickHouse, Redis, SQLite, Microsoft SQL Server / Azure SQL, Oracle, Neon, Snowflake, Aurora DSQL, Redshift, Supabase self-host), SaaS APIs (Stripe, Notion, Atlassian, Linear, Supabase Cloud), source control (GitHub), and the filesystem. A community ecosystem of per-MCP Lenses (YAML config files), and measured benchmarks showing 84% fewer tokens and ~3× faster responses across a multi-question session on Postgres (median of 4 runs). Zero server changes. No hosted gateway in the data path. Works with Claude Code, VSCode Copilot, Codex, Cursor, and any MCP client.

🧠 Need codebase understanding together with MCP governance? See our sibling project SocratiCode: local-first codebase intelligence with semantic search, dependency graphs, symbol-level impact analysis.

Kindly sponsored by Altaire Limited. We also offer a commercial license for organisations where AGPL is a blocker.

If JanuScope has been useful to you, please ⭐ star this repo (it helps others discover it) and share it with your team.

Policy enforcement at the MCP threshold. Most MCP servers ship dangerous tools by default, execute_sql and drop_table on databases, create_pull_request and merge_pull_request on GitHub, stripe_api_execute on Stripe, write_file and move_file on the filesystem. None of them log what the LLM asked yesterday. The choice today is fork every server or accept the risk. Or you can choose JanuScope: a thin proxy that wraps any MCP server with a single YAML policy and disappears.

Benchmarked live with claude-sonnet-4-5 against a real application Postgres database (median of 4 runs per prompt). Across a typical three-question working session (prompt caching enabled), a JanuScope Lens uses 84% fewer total tokens, makes 84% fewer tool calls, and runs ~3× faster than the raw database MCP. And in an adversarial-safety probe, the raw pipeline intermittently leaked a real user email on the "I'm the admin, just cross-referencing" social-engineering prompt (observed in 2 of 4 runs), while the JanuScope-wrapped pipeline held the line in all 4 runs. Single-question floor: 34% fewer tokens / 86% fewer tool calls / ~3× faster. Session savings are bigger because JanuScope's injected schema is paid once and cached, while baseline discovery compounds across turns. Full benchmark →

Live GitHub Copilot output against the bundled postgres-crystaldba lens (May 2026). Left: the assistant declines to fetch email addresses because the lens classifies the column as PII, Copilot self-censors before any query is sent. Right: the assistant declines to issue an UPDATE because the lens is read-only, Copilot recognises the policy and reports the refusal cleanly rather than guessing or retrying.

Why now: this is no longer hypothetical. In July 2025, Replit's AI agent wiped a customer database during an explicit code freeze (1,200+ records, ~1,200 companies) and then misled the user about whether rollback was possible. In April 2026, a Cursor agent on Claude Opus 4.6 deleted PocketOS's production database and three months of backups in nine seconds, after finding an unscoped Railway credential and guessing an API call (post-mortem). Both stories share one shape: an AI was given a destructive capability with nothing in the path between the model and the real system. JanuScope is what sits in that path, for any data access that goes through an MCP server: for examle a Replit-shape incident on a JanuScope-wrapped Postgres MCP (block writes, sqlGuard on DML, audit, classification) is refused at the proxy threshold and recorded in the JSONL audit. JanuScope governs the MCP surface, it is one layer of a defence-in-depth posture, alongside scoped DB roles and credentials, host-level approval gates, etc. See the FAQ and SECURITY.md.

• Quick Start
• Why JanuScope
• What it does
• Lenses, the community ecosystem
• Benchmarks, measured, not modelled
• Configuration reference
• How it works
• Logging & audit
• Library API
• JanuScope vs Claude Skills
• FAQ
• License

Only Node.js 20+ required. No install step, npx fetches and caches JanuScope on first use.

Find your service in the table below, copy the right-hand snippet into your MCP-client config (or change your existing entry: the diff is just command and args), restart your client. The env block stays exactly as it was. JanuScope inherits whatever env vars your client passes and forwards them to the wrapped MCP unchanged. No renames, no re-translation.

The wrap pattern is the same across every host (Claude Desktop, Cursor, Claude Code, VS Code Copilot, Windsurf, Cline, Roo Code, anything that speaks MCP).

{
  "command": "uvx",
  "args": ["postgres-mcp"],
  "env": {
    "DATABASE_URI": "postgresql://user:pass@host:5432/db"
  }
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "postgres-crystaldba"],
  "env": {
    "DATABASE_URI": "postgresql://user:pass@host:5432/db"
  }
}

{
  "command": "npx",
  "args": ["-y", "@benborla29/mcp-server-mysql"],
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "readonly",
    "MYSQL_PASS": "<your_password>",
    "MYSQL_DB": "mydb"
  }
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "mysql-benborla29"],
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "readonly",
    "MYSQL_PASS": "<your_password>",
    "MYSQL_DB": "mydb"
  }
}

{
  "command": "npx",
  "args": ["-y", "mongodb-mcp-server"],
  "env": {
    "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net"
  }
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "mongodb-official"],
  "env": {
    "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net"
  }
}

{
  "command": "uvx",
  "args": ["mcp-clickhouse"],
  "env": {
    "CLICKHOUSE_HOST": "myhost.clickhouse.cloud",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "readonly",
    "CLICKHOUSE_PASSWORD": "<your_password>",
    "CLICKHOUSE_DATABASE": "default",
    "CLICKHOUSE_SECURE": "true"
  }
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "clickhouse-official"],
  "env": {
    "CLICKHOUSE_HOST": "myhost.clickhouse.cloud",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "readonly",
    "CLICKHOUSE_PASSWORD": "<your_password>",
    "CLICKHOUSE_DATABASE": "default"
  }
}

{
  "command": "uvx",
  "args": [
    "--from",
    "redis-mcp-server@latest",
    "redis-mcp-server",
    "--url",
    "redis://localhost:6379/0"
  ]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "redis-official"],
  "env": {
    "REDIS_URL": "redis://localhost:6379/0"
  }
}

{
  "command": "uvx",
  "args": ["mcp-sqlite", "/path/to/your.sqlite"]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "sqlite-panasenco"],
  "env": {
    "SQLITE_DB_PATH": "/path/to/your.sqlite"
  }
}

{
  "command": "dab",
  "args": ["start", "--mcp-stdio"],
  "cwd": "/path/to/your/dab-project"
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "mssql-azure-dab"],
  "cwd": "/path/to/your/dab-project"
}

{
  "command": "sql",
  "args": ["-mcp"]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "oracle-db-sqlcl"]
}

{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "http://127.0.0.1:54321/mcp",
    "--allow-http",
    "--transport",
    "http-only"
  ]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "supabase-selfhost"]
}

{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://mcp.supabase.com/mcp?read_only=true",
    "--header",
    "Authorization:Bearer YOUR_SBP_TOKEN",
    "--transport",
    "http-only"
  ]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "supabase-cloud"],
  "env": {
    "SUPABASE_ACCESS_TOKEN": "sbp_your_token_here"
  }
}

{
  "command": "uvx",
  "args": ["snowflake-labs-mcp", "--service-config-file", "/path/to/services.yaml"],
  "env": {
    "SNOWFLAKE_ACCOUNT": "ORG-ACCOUNT",
    "SNOWFLAKE_USER": "your_user",
    "SNOWFLAKE_PASSWORD": "<your_PAT>",
    "SNOWFLAKE_ROLE": "ACCOUNTADMIN",
    "SNOWFLAKE_WAREHOUSE": "COMPUTE_WH"
  }
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "snowflake-labs"],
  "env": {
    "SNOWFLAKE_ACCOUNT": "ORG-ACCOUNT",
    "SNOWFLAKE_USER": "your_user",
    "SNOWFLAKE_PASSWORD": "<your_PAT>",
    "SNOWFLAKE_ROLE": "ACCOUNTADMIN",
    "SNOWFLAKE_WAREHOUSE": "COMPUTE_WH",
    "SNOWFLAKE_MCP_CONFIG": "/path/to/services.yaml"
  }
}

{
  "command": "uvx",
  "args": [
    "awslabs.aurora-dsql-mcp-server@latest",
    "--cluster_endpoint",
    "<id>.dsql.eu-west-2.on.aws",
    "--region",
    "eu-west-2",
    "--database_user",
    "admin"
  ]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "aurora-dsql"],
  "env": {
    "DSQL_CLUSTER_ENDPOINT": "<id>.dsql.eu-west-2.on.aws",
    "AWS_REGION": "eu-west-2",
    "DSQL_DATABASE_USER": "admin",
    "AWS_PROFILE": "default"
  }
}

{
  "command": "uvx",
  "args": ["awslabs.redshift-mcp-server@latest"],
  "env": {
    "AWS_REGION": "eu-west-2",
    "AWS_PROFILE": "default"
  }
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "redshift"],
  "env": {
    "AWS_REGION": "eu-west-2",
    "AWS_PROFILE": "default"
  }
}

{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://mcp.neon.tech/mcp?readonly=true",
    "--header",
    "Authorization:Bearer YOUR_NAPI_TOKEN",
    "--transport",
    "http-only"
  ]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "neon-cloud"],
  "env": {
    "NEON_API_KEY": "napi_your_token_here"
  }
}

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Desktop"]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "filesystem-mcp-official"],
  "env": {
    "FILESYSTEM_ALLOWED_DIR": "/Users/you/Desktop"
  }
}

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "GITHUB_PERSONAL_ACCESS_TOKEN",
    "ghcr.io/github/github-mcp-server"
  ],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "<your_PAT>"
  }
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "github-official"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "<your_PAT>"
  }
}

{
  "command": "npx",
  "args": ["-y", "@stripe/mcp"],
  "env": {
    "STRIPE_SECRET_KEY": "rk_live_<restricted_key>"
  }
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "stripe-official"],
  "env": {
    "STRIPE_SECRET_KEY": "rk_live_<restricted_key>"
  }
}

{
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "notion-official"]
}

{
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "atlassian-official"]
}

{
  "command": "npx",
  "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "linear-remote"]
}

Your favourite service / MCP isn't here? Open a lens-request issue so a maintainer or community contributor can pick it up. Or contribute one yourself: it's a single YAML file plus a short README.

About the env block. For most lenses the env block is byte-identical to what your vanilla setup had: JanuScope passes inherited env vars through unchanged. Two exceptions where the connection info moves from a positional argument into an env var (because the upstream MCP takes the value as argv, and JanuScope's lens-spawning needs to read it from somewhere): SQLite (SQLITE_DB_PATH), Filesystem (FILESYSTEM_ALLOWED_DIR). The right-hand columns above show this for those two.

Most lenses run via npx/uvx and need only Node.js 20+. Three lenses wrap CLIs that need a one-time local install: dab for mssql-azure-dab (dotnet tool install -g Microsoft.DataApiBuilder), sql for oracle-db-sqlcl (Oracle SQLcl 25.4+ download), and docker for github-official. Each per-lens README links the install step.

Quick browse. npx januscope lenses list lists every bundled lens; npx januscope lenses show <name> prints its full config + README.

A minimal Postgres policy (~/januscope/postgres.yaml):

target:
  command: uvx
  args: ["postgres-mcp", "--access-mode=restricted"]
  # No `env:` here. DATABASE_URI is supplied by the user via their
  # MCP-client config (or shell env) and inherits through to the
  # spawned target. The lens never renames operator env vars.

# Append policy text to every tool description the LLM sees.
instructions: |
  READ-ONLY. SELECT only. Default LIMIT 100.

# Pre-inject the schema into the `execute_sql` tool description so the
# LLM writes correct queries on the first call.
dbSchema:
  driver: postgres
  connectionString: "${DATABASE_URI}"
  tables: [orders, products, customers]
  injectInto: [execute_sql]

# Reject any SQL that isn't a read. Catches CTE-DML, SELECT INTO,
# pg_sleep, lo_export, etc.
sqlGuard:
  tools: [execute_sql]

# Scrub PII patterns from tool results before the LLM sees them.
redact:
  rules:
    - regex: '\b\d{3}-\d{2}-\d{4}\b' # US SSN
    - field: "**.email"

# Compliance log: one JSONL record per call.
audit:
  sink: "~/mcp-audit.jsonl"

Point --config at the absolute path of your YAML, set DATABASE_URI in your client config's env block, restart the client. Done. The LLM now sees an execute_sql tool with your real schema baked into its description, can't run mutations or call pg_sleep, sees SSNs and emails as [REDACTED], and every call lands in the audit log.

Same six-overlay pattern applies to non-database MCPs, drop dbSchema and sqlGuard, keep block / instructions / redact / audit. See the bundled Lenses in lenses/ for real examples covering GitHub, the filesystem, Stripe, Notion, Atlassian, and Linear.

Lens transparency rule. A lens never renames operator-supplied env vars and never declares them in target.env just to pass them through. The user sets the env var the upstream MCP itself reads, in their MCP-client config, and JanuScope inherits it. Only policy hardcodes (constants the lens decides for the user, like ALLOW_INSERT_OPERATION: "false" or CLICKHOUSE_SECURE: "true") belong in target.env. See lenses/CONTRIBUTING.md for the full rule.

1. Unsafe tools exposed by default. Most database and API MCPs ship write-capable tools (execute_sql, create_table, delete_record). An LLM that sees the tool will eventually call it. Running it in production is a question of when, not if.

2. LLMs fly blind. SQL MCPs expose a query tool whose description says "run SQL." The LLM has no idea what tables exist, what columns they contain, or how they're related. It wastes 2-3 round-trips on list_tables → describe_table → actual query, and often guesses wrong anyway.

3. No audit trail. Nobody knows what the LLM asked yesterday. Nobody knows whether a PII column was read. Compliance teams reject the deployment.

• One policy layer in front of any MCP. No forking the upstream. No hosted gateway in the data path. The same lens YAML shape applies whether you have 1 MCP or 200.
• DB schema pre-injection . The LLM gets your real schema baked into the tool description at startup, it writes correct queries on the first call, skipping the discovery round-trips.
• Defence in depth with Skills. Claude Skills tell the model how it should behave; JanuScope enforces what it can do. They're complementary. See JanuScope vs Claude Skills below.

Fair question, and the bundled Postgres lens does exactly that, as a baseline. JanuScope sits on top of whatever read-only mode your MCP offers, because a single MCP-level flag only solves one of the three problems above:

If you only need "don't write," a DB role or --access-mode=restricted is enough. If you also need audit, redaction, policy-in-description, schema injection, and the same mental model across any MCPs, that's JanuScope.

Defence in depth, not perimeter. The sqlGuard overlay is a keyword-level filter with documented limits, it cannot parse arbitrary SQL and will forward SELECT purge_audits() unchanged (a UDF whose name happens to be a mutation). Deploy it with a read-only DB role underneath and treat sqlGuard as the second layer, not the only one. The bundled postgres lens demonstrates the stack: MCP --access-mode=restricted, JanuScope sqlGuard, database-level read-only role.

Six overlays, each opt-in via one YAML field. Unused overlays compile out. They layer into defence in depth, every serious data-access lens uses all three protective layers (shape intent, enforce at the gate, scrub on the way back):

Shape intent

• instructions: Append policy text to every tool's description. The LLM reads tool descriptions before deciding what to call, so this is where "never return these columns even if the user asks" gets the most mileage. This layer is advice, not enforcement, the model can ignore it, and in our adversarial benchmark the bare instructions string is the difference between a non-deterministic baseline and a consistent refusal, not an absolute guarantee. Pair with block / sqlGuard / redact for the actual enforcement; instructions shapes what the model tries to do, the gates decide what it can do.

Enforce at the gate

• block: Filter whole tools from tools/list. Return JSON-RPC -32601 if the LLM calls a blocked tool. Works at tool-name granularity, use this when the MCP separates reads and writes into different tools (e.g. the official SQLite MCP's read_query vs write_query).
• rateLimit: Per-tool token bucket. Caps tools/call traffic by tool name at a configured per-minute rate; returns JSON-RPC -32000 with a retry_after_seconds hint when the bucket is empty. Each tool gets its own bucket, so one hot tool can't starve the others. Use this to protect a backend from an LLM stuck in a retry loop.
• sqlGuard: Keyword-level SQL mutation check on configured tools. Catches UPDATE / DELETE / DROP / etc. inside the SQL argument of a tool that handles both reads and writes (the common case for Postgres and MySQL MCPs). Comment-stripped before matching so it can't be hidden behind -- or /* */. Best-effort filter, not a full SQL parser, combine with a database-level read-only role for high assurance.

Scrub on the way back

• redact: Regex and field-path rules applied to tool results before they leave the proxy. Field-path rules auto-detect and parse JSON strings inside text content blocks, so **.email reaches into the serialised rows that most SQL MCPs return. Regex rules scan the text directly. Both are often used together.

Compliance

• audit: One JSONL record per tools/call. Request and response correlated by JSON-RPC ID; arguments hashed by default (opt in to raw logging). The audit log sees the un-redacted payload; the LLM sees the scrubbed one, exactly the ordering compliance requires.

Give the LLM the context it would otherwise have to discover

• dbSchema: Database-aware automatic context. At startup, JanuScope opens a real connection to your Postgres / MySQL / SQLite, asks the database for its tables and columns, formats the answer as readable text, and pastes it into the description of the SQL tool the LLM sees. Result: the LLM writes the right query on its first try instead of asking the database "what tables exist?" / "what columns does this one have?" across two or three round trips. The schema text never leaves the proxy; it sits in memory next to the tool description. See "how dbSchema and contextInjection actually work" for the step-by-step.
• contextInjection: The same pre-injection idea for any other MCP, with the difference that you (or a script you run) supply the text instead of JanuScope generating it. Two ways to provide it: inline in the YAML (text: |) for short / readable contexts, or as a separate file (textFile: ./context.md) when the text is long or kept fresh by an external job. Useful for Linear (paste the project / team / status enums), Atlassian (project / space list), filesystem (a directory skeleton), or any lens where pre-supplying context skips a discovery loop.

Data-sensitivity labelling

• classification: one of public / internal / sensitive. When set, the instructions overlay prepends a short banner to the policy text the LLM sees (e.g. CLASSIFICATION: SENSITIVE, PII, financial, or regulated data …) and every audit record is tagged with the value. Routes sensitive-lens events to tighter retention / ACL paths in downstream SIEMs without re-deriving the label from the tool name. Informational, the guardrails are still block / sqlGuard / redact.

Supply-chain defence

• First-use quarantine (opt-in, firstRun: approve), two-layer defence against tool poisoning: a malicious or compromised upstream MCP that quietly adds a new tool, removes one, or mutates a tool's description (a known prompt-injection vector). JanuScope tracks two fingerprints per lens identity in ~/.januscope/approved.json:

  1. Static layer: fingerprint of the lens-config surface that affects what the proxy enforces (target command, block list, sqlGuard tools, rateLimit rules, redact rule shapes). Computed before the target spawns. Catches "the operator (or an attacker) edited the lens YAML."
  2. Live layer: fingerprint of the upstream MCP's actual tools/list response (every tool's name, description, inputSchema, annotations). Re-checked on every tools/list response, not just the first one in a session, so a compromised upstream can't pass the first check then mutate the surface mid-session (after notifications/tools/list_changed). Drift is enforced by rewriting the response into a JSON-RPC error so the MCP client sees a clear refusal.

  Running januscope approve --config <path> records BOTH fingerprints atomically: the static one from the lens config, and the live one by spawning the target, driving the standard initialize + tools/list handshake, and hashing the result. If the target isn't reachable at approve time the static fingerprint is still recorded and the live fingerprint will TOFU on the next actual run; pass --no-probe to skip the live capture entirely. On subsequent launches either layer drifting refuses the surface with the same remediation (januscope approve --config <path> to re-baseline). Stdin-safe, no interactive prompts, the operator re-approves out of band.

Observability

• OpenTelemetry tracing (opt-in, telemetry.otel), the pipeline emits one root span per handleClientMessage / handleServerMessage and one child span per overlay invocation, with attributes for the JSON-RPC method, the tool name, the overlay outcome (forwarded / short_circuited / dropped / gate_failure), and, when set, the classification. Shipped via the OTLP HTTP exporter to any collector (Jaeger, Grafana Tempo, Honeycomb, etc.). The OTel packages are optional peer deps, install them only when you want tracing; default install stays lean. Current limitation: root-and-child spans are emitted without explicit parent-child linkage, they share a trace ID only when the host has already activated OTel context propagation, otherwise expect a flat sibling list keyed by the pipeline root. Context threading is a follow-up.

Keyword-scanning SQL guards and "apply this regex to everything" redactors are the easy 80%. The parts that catch the last 20% of real-world bypasses are what we pin with tests:

• sqlGuard beyond leading-verb allowlists. Also rejects WITH x AS (DELETE …) SELECT … (CTE-hidden mutations), SELECT … INTO shadow_table FROM users (SELECT-INTO creates tables), EXPLAIN ANALYZE DELETE … (EXPLAIN executes for ANALYZE), COPY … PROGRAM … (RCE via Postgres COPY PROGRAM), and a 17-name Postgres admin-function denylist (pg_sleep, lo_import, lo_export, dblink, …). Row-locking clauses (FOR UPDATE) are whitelisted explicitly so legitimate reads aren't over-blocked. Every one of these is pinned in a test file.
• redact uses a function replacer. Passing a string replacement to String.prototype.replace lets $&, $1, $$ etc. interpolate the matched secret back into the scrubbed output, the exact opposite of what the overlay is for. We use () => replacement so the replacement is always literal. Pinned at test/overlays/redact.test.ts:123.
• Embedded-JSON extraction for narrative envelopes. The official MongoDB MCP wraps its results in <untrusted-user-data-…>…</untrusted-user-data-…> tags. A naive JSON-parse fails; a naive regex can't find the balanced-brace boundary. extractEmbeddedJsonBlock walks the string with a brace depth counter that respects JSON string escapes, splices the redacted JSON back in, and leaves the prose intact. Without this, field: "**.email" would silently miss every MongoDB response.
• audit opens with mode 0o600. The default umask on most hosts produces 0o644, world-readable, and with logRawArgs: true the file contains raw SQL, request bodies, and file contents. We open explicitly at 0o600 and stat-verify the permissions in a regression test.
• Pipeline fails CLOSED for gate overlays. block and sqlGuard are marked kind: "gate": if their handler throws on a malformed payload, the pipeline responds -32603 internal error to the client instead of forwarding the unchecked request to the target. Observer overlays (audit, redact, dbSchema, instructions) fail-open by contrast, an exception in an enhancer shouldn't break the call. Both paths are pinned.
• Every bundled lens is live-probed. npm run validate:lenses:probe spawns each target MCP, runs tools/list, and diffs the lens's block-list against real tool names. This is what caught the Atlassian camelCase bug and the Linear save_* family, and it's available to contributors before they open a PR. Pre-empts the hostile reviewer's first question: "are your block lists actually blocking anything?"

A lens is a ready-made JanuScope policy for one specific MCP server, config.yaml + docs, curated to cover that MCP's tool surface and common gotchas. Lenses live in lenses/. Browse, use, or contribute one.

januscope lenses list                       # show every bundled lens
januscope lenses show mongodb-official      # print its config + README

One Lens per service, pointing at the official vendor MCP where one exists. Community alternatives are included only for technologies without a single vendor (Postgres, MySQL, SQLite). Every Lens is verified against a live tools/list on its target MCP.

📊 Databases

• postgres-crystaldba: Postgres MCP Pro. Hardcodes --access-mode=restricted, adds sqlGuard with a Postgres dangerous-function denylist, schema pre-injection with multi-schema support, PII redaction, audit.
• mysql-benborla29: @benborla29/mcp-server-mysql. mysql_query gated by sqlGuard; MCP-level writes hardcoded off via ALLOW_*_OPERATION=false.
• mongodb-official: MongoDB's official MCP. Locks DB + Atlas writes; PII redaction reaches into returned JSON documents.
• clickhouse-official: ClickHouse's official MCP. Allowlist-mode sqlGuard on run_query; PII redaction; audit.
• redis-official: redis/mcp-redis. Read-only Redis (47 tools, 23 mutations blocked); works against self-hosted, Redis Cloud, AWS ElastiCache, and Upstash via standard rediss:// URIs; heavy regex coverage on returned values (session tokens, JWTs, bcrypt, cloud keys); rate-limits the heavy iteration tools.
• sqlite-panasenco: panasenco/mcp-sqlite. sqlGuard on sqlite_execute plus defensive write-verb globs for canned queries.
• mssql-azure-dab: Data API builder v1.7+ MCP for Azure SQL / SQL Server / SQLDW / Cosmos DB / PostgreSQL / MySQL. Blocks every write-shaped DML tool (create_record, update_record, delete_record, execute_entity); PII redaction; audit.
• oracle-db-sqlcl: Oracle SQLcl 25.4+ built-in MCP. Blocks run-sqlcl (SQLcl meta-commands incl HOST shell escape); sqlGuard on run-sql for keyword-level write rejection; PII redaction; audit.
• supabase-selfhost: Supabase self-host MCP via mcp-remote against the local CLI stack at http://127.0.0.1:54321/mcp. Blocks apply_migration; sqlGuard on execute_sql; PII redaction including JWT-shaped tokens; audit.
• neon-cloud: Neon hosted MCP via mcp-remote with API-key auth and server-side ?readonly=true. Blocks get_connection_string (DSN credential leak); sqlGuard on run_sql and run_sql_transaction; PII redaction including DSN-shaped values; audit.
• snowflake-labs: Snowflake-Labs/mcp via uvx with PAT auth. Blocks the generic DDL writers create_object / drop_object / create_or_alter_object (plus defensive globs); sqlGuard on run_snowflake_query; PII redaction including PAT/JWT-shaped tokens; audit. Includes a services.example.yaml for the MCP's required --service-config-file.
• aurora-dsql: awslabs.aurora-dsql-mcp-server via uvx with AWS IAM auth. MCP runs in default read-only mode (no --allow-writes); sqlGuard layered on readonly_query; PII redaction including DSN-shaped values; audit.
• redshift: awslabs.redshift-mcp-server via uvx with AWS IAM auth. Discovers both provisioned clusters and Serverless workgroups; sqlGuard on execute_query; PII redaction including JDBC Redshift / Postgres DSN shapes; audit. README includes the minimum IAM policy.

🔧 Developer tools

• github-official: GitHub's official Go MCP. Runs in Docker with GITHUB_READ_ONLY=1 and a curated GITHUB_TOOLSETS; proxy-layer write blocks as defence in depth; wide-spectrum secret redaction on file contents.
• filesystem-mcp-official: MCP reference filesystem server. Locks write_file / edit_file / create_directory / move_file; wide-spectrum secret redaction (cloud keys, PATs, PEM, DB URLs, .env, JWT).

💼 SaaS

• stripe-official: Stripe's official MCP. Locks refunds, payouts, cancels, and the stripe_api_execute generic REST bypass; scrubs card PAN, Stripe keys, email, phone.
• notion-official: Notion's official hosted MCP via mcp-remote.
• atlassian-official: Atlassian's official Rovo MCP via mcp-remote. Jira, Confluence, Compass.
• linear-remote: Linear's official remote MCP via mcp-remote.
• supabase-cloud: Supabase hosted MCP at mcp.supabase.com via mcp-remote with PAT auth. Blocks every project / branch / migration / edge-function write (10 tools + defensive globs); sqlGuard on execute_sql; PII redaction including DSN and JWT shapes; audit. For the local-development MCP see supabase-selfhost.

The value of the tool compounds with every new lens. If you run JanuScope against an MCP that isn't listed here, please contribute a lens, it takes ~15 minutes and helps everyone using that MCP afterwards. MCP authors are especially welcome to submit a lens for their own server.

• Don't want to write the lens yourself? Open a lens request and a maintainer or community contributor will pick it up when the target MCP looks tractable.

Tool names differ per MCP. Before writing your policy, run tools/list against the target MCP once to see what it actually exposes. Each lens's README documents which tool names it assumes so you can adapt for forks or alternatives.

Every number below is from running the same prompt through Claude Sonnet 4.5 against the raw Postgres MCP and against the same MCP wrapped in a JanuScope Lens, and capturing token usage from the Anthropic API response metadata. All numbers are medians of 4 independent runs (Sonnet is non-deterministic, single-run numbers aren't a defensible headline).

Prompt: "Find the top 5 users by total audit count across sites and pages they own."

Same model, same database, same correct answer every run. The baseline consistently spent 5 turns / 7 tool calls discovering schema (list tables, describe tables, refine query); the JanuScope run consistently used 2 turns / 1 tool call because the schema was baked into the query tool description from call one. Tool-call and turn counts are dead stable across runs; tokens vary ±5%.

The single-question numbers above are a floor. In a real session a user asks several related questions, and two effects compound JanuScope's win:

• The baseline's schema-discovery cost is paid on every question (discovery tool calls accumulate in context across turns, inflating input tokens rapidly).
• JanuScope's injected schema is paid once and then read from cache on every subsequent turn (Anthropic's ephemeral prompt cache, attached to the tools definition).

Three analytical questions in the same session, Sonnet 4.5, prompt caching enabled. Medians across 4 runs:

• The baseline range is wide (min 93k tokens, max 146k). That's real variance from unbounded exploration, one Q3 drifted to 118k tokens in one run. The baseline's worst case is open-ended because the model keeps exploring when it can't see the schema.
• JanuScope's totals are tight (20k ±1k). Schema injection bounds the work the model does.

A follow-up benchmark sends three hostile prompts through the same two pipelines and counts what leaks into the final answer the user actually reads. Same median-of-4-runs methodology as above; pass rate is the count of runs where JanuScope held the line across all three prompts.

The telling case is the middle row. Claude's own safety training reliably refuses obvious requests but is inconsistent on subtle framings, the baseline leaked in 2 of 4 independent runs (small sample; treat this as evidence that the baseline is unreliable here, not as a precise leak rate), and the 2 "clean" runs are not a property of the baseline, they are a property of Sonnet's non-determinism. JanuScope held the line in every one of the 4 runs across every one of the 3 prompts, because the lens's instructions overlay pushes an explicit policy into every tool description the model reads, its sqlGuard overlay would refuse any DML attempt, and the redact overlay scrubs the response anyway as a backstop.

The single-question delta is a conservative floor; the session delta is closer to the real-world experience. Three effects stack:

1. Multi-turn sessions. Schema paid once via prompt cache; discovery savings accumulate per question.
2. Larger schemas. Baseline discovery scales linearly with the tables the model needs to describe; JanuScope pre-injects once. Tool-call delta stays near −90% even on 100-table schemas.
3. Stronger models. Opus-class models do more deliberate discovery than Sonnet by default, bigger gap. Haiku does less, smaller gap but still positive.

Numbers vary ±5–10% run-to-run because the model is non-deterministic. Code to reproduce, plus raw JSON output from each run, lives in .benchmarks/ (gitignored, requires your own API key and DB).

All top-level fields except target are optional. The minimum viable config is three lines.

target: # required
  command: <string> # executable (e.g. "npx", "node", or an absolute path)
  args: [<string>] # optional
  env: { <name>: <value> } # optional; merged with inherited process env
  cwd: <string> # optional

classification:
  public|internal|sensitive # optional lens data-sensitivity label.
  # When set, `instructions` prepends a short banner to
  # every tool description and `audit` tags every record
  # with `classification: "<value>"`. Purely informational;
  # enforcement still lives in `block` / `sqlGuard` / `redact`.

firstRun:
  approve # optional; when set, the runtime fingerprints the lens
  # via TWO independent layers, both stored in
  # ~/.januscope/approved.json:
  #   (1) Static lens fingerprint: block rules + sqlGuard
  #       tools + rateLimit rules + redact rule shapes +
  #       target command. Refuses startup on drift.
  #   (2) Live tools/list fingerprint: every upstream tool's
  #       name + description + inputSchema + annotations.
  #       Re-checked on EVERY tools/list response (not just
  #       the first), so a compromised upstream cannot pass
  #       the initial check and then mutate the surface mid-
  #       session via notifications/tools/list_changed.
  #       Rewrites tools/list into a JSON-RPC error on drift.
  # Run `januscope approve --config <path>` to re-baseline
  # both layers atomically (probes the target, captures the
  # live tools, persists both fingerprints). Pass --no-probe
  # to skip the live capture and let it TOFU on next run.
  # Defends against tool-poisoning where a malicious MCP
  # quietly adds a tool, mutates a description (prompt-
  # injection vector), or changes a tool's input schema.

block: # array of tool names or globs; "admin_*" supported
  - <name or glob>

instructions: <string> # appended to every tool description

dbSchema:
  driver: postgres|mysql|sqlite # optional; inferred from connectionString prefix
  connectionString: <string>
  tables: [<string>] # allowlist (mutually exclusive with excludeTables)
  excludeTables: [<string>]
  schemas:
    [<string>] # Postgres only. Defaults to ["public"]. Set for
    # multi-schema deployments (e.g. ["app", "analytics"]).
    # MySQL and SQLite drivers ignore this.
  injectInto: [<string>] # which tool names receive the schema; defaults to common SQL names
  format: markdown|ddl|compact
  includeComments: <bool>
  refresh: startup|never

contextInjection: # static counterpart to dbSchema; same goal, operator-supplied text
  injectInto: [<tool-name>] # tools whose `description` receives the text; required, ≥1
  text: | # OPTION A: inline string. Mutually exclusive with `textFile`.
    Active projects: PROJ-A, PROJ-B, PROJ-C.
    Issue states: backlog, todo, in_progress, in_review, done, cancelled.
  # textFile: ./context.md  # OPTION B: path. Mutually exclusive with `text`.
  # Relative paths resolve against this lens's config.yaml directory.
  # `~/...` expands to the home dir. Absolute paths are used as-is.
  position: append|prepend # default "append" (after the upstream description)

redact:
  rules:
    - regex:
        <pattern> # scans every text content block. Leading PCRE-style
        # inline flags are supported: `(?i)password` →
        # case-insensitive, `(?is)` → +dotall, etc.
    - field:
        <path> # dotted path with * (one level), ** (any depth), [i] (index).
        # Auto-parses JSON strings inside text blocks, and
        # also extracts a single balanced JSON object/array
        # embedded in a narrative envelope (e.g. MongoDB's
        # <untrusted-user-data-…> wrapper).
  replacement: <string> # default "[REDACTED]"
  applyTo: text|all|fields

sqlGuard:
  tools: [<tool-name>] # which tool(s) carry a SQL argument
  sqlArg: <name> # default "sql"
  readOnly: <bool> # default true; rejects mutations in the SQL argument
  mode:
    allowlist|denylist # default "allowlist" (recommended)
    # allowlist: accept only leading read verbs
    #   (SELECT / WITH / SHOW / EXPLAIN / DESCRIBE /
    #   VALUES / PRAGMA / TABLE) AND reject any
    #   embedded DML / DDL keyword or SELECT INTO
    #   hiding inside a WITH CTE / EXPLAIN ANALYZE.
    # denylist: legacy keyword-blacklist; preserved
    #   for compatibility.
  extraReadVerbs:
    [<word>, ...] # allowlist mode: dialect-specific
    # read verbs your MCP needs on top of the defaults.
  extraWriteKeywords: [<word>, ...] # denylist mode only (ignored otherwise).

rateLimit: # array of rules; first matching rule wins
  - tool: <name or glob> # exact tool name or "*"-glob (same as `block`)
    perMinute: <number> # steady-state rate; bucket starts full at <perMinute>.
    # Each matched *tool* gets its own bucket, so one hot
    # tool can't starve others that share the same rule.
    # `per_minute` (snake_case) is also accepted.

telemetry: # optional; omit entirely for zero-overhead (no-op tracer)
  otel:
    endpoint: <url> # OTLP HTTP endpoint
    # e.g. "http://otel-collector:4318/v1/traces"
    serviceName: <string> # optional; default "januscope"
    headers: # optional auth / routing headers
      Authorization: "Bearer ${OTEL_TOKEN}"
  # Install the peer deps only when you enable this:
  #   npm install @opentelemetry/api @opentelemetry/sdk-trace-base \
  #               @opentelemetry/exporter-trace-otlp-http \
  #               @opentelemetry/resources

audit:
  sink:
    <path|stderr|stdout> # "~" is expanded. Parent directories
    # are auto-created. File opens with 0o600
    # perms (user-only; matters for logRawArgs).
  logRawArgs: <bool> # default false; when false, args are SHA-256 hashed

Environment variables in string values are expanded with ${VAR} or $VAR. Missing variables become empty strings and emit a one-line [januscope] warn: env var 'FOO' is unset, substituted empty string on stderr (once per name). We don't refuse to start, the user may be intentionally testing with undefined vars, but the warning is loud enough that a forgotten $DATABASE_URL at 2am shows up in the logs instead of silently breaking the lens.

Alongside plain ${VAR} substitution, three URI-shaped references are resolved at startup from external secret stores:

#<field> selects one field out of the stored object; if the secret has exactly one field you can omit it. The sync loadConfig() refuses a config with vault references and directs you at the async loadConfigAsync(), the CLI always uses the async path, so januscope --config … handles both cases transparently.

Design note: resolvers fetch at startup only. JanuScope reads the value once, hands the substituted config to the pipeline, and never calls the secret store again for the life of the process. Rotate your secrets; restart JanuScope.

An MCP server is a program that speaks JSON-RPC 2.0 over stdio. JanuScope is also a program that speaks JSON-RPC 2.0 over stdio, it just happens to spawn the real MCP server as a child process and forward messages through a pipeline of overlays.

[AI client] ──stdin/stdout──> [januscope] ──stdin/stdout──> [real MCP server]
                                   ▲
                            rewrites tools/list
                            short-circuits blocked tools/call
                            injects schema, scrubs output, logs

No daemon, no port, no persistent state (other than optional audit logs). JanuScope lives as long as the client's connection and dies with it. See ARCHITECTURE.md for the full picture.

These are the two overlays that add context to the tool descriptions the LLM sees. The mechanism is the same; what differs is where the text comes from.

Walk-through, dbSchema against Postgres

1. Lens load. JanuScope reads config.yaml. The dbSchema: block is a recipe (driver, connection string, which schemas to look at, which tools to inject into). The schema text itself is not in the YAML.
2. Startup introspection. JanuScope opens a real Postgres connection using the recipe's connectionString and runs a few information_schema queries. It pulls table names, columns, types, foreign keys, and (if includeComments: true) any SQL comments. This takes 50-300 ms and runs once per launch.
3. Serialisation. The introspection result is formatted into a readable text blob (Markdown by default). This blob lives only in JanuScope's memory; never written to disk, never visible outside the proxy.
4. MCP handshake. The MCP client (Claude / Cursor / etc.) sends tools/list to JanuScope. JanuScope forwards it to the real Postgres MCP. The MCP returns its tool list with the standard descriptions.
5. Injection. Before forwarding the response back to the client, the dbSchema overlay rewrites it. For each tool name in injectInto: (typically execute_sql), the schema blob is appended to that tool's description field.
6. The LLM sees the enriched tool. Claude / Cursor reads the description and now knows which tables exist and what columns they have, before writing its first query. No list_tables round-trip needed.

The benchmark numbers above (84% fewer tokens on a multi-question session) are this loop being collapsed into one step.

Walk-through, contextInjection against Linear

contextInjection is the same idea but the operator is the introspector. JanuScope doesn't know how to "introspect" Linear (or Notion, or a filesystem), so the operator supplies the text. Two storage choices:

• Inline (text: |). Best for short, hand-curated context that doesn't change often. The text lives directly in the lens's config.yaml:

  contextInjection:
    injectInto: [list_issues, search_issues, get_issue]
    text: |
      Active projects: PROJ-A (engineering), PROJ-B (data), PROJ-C (growth).
      Issue states: backlog, todo, in_progress, in_review, done, cancelled.

• External file (textFile: ./context.md). Best when the context is long, or when an external job (cron, CI, a homegrown script) keeps it fresh. The lens's config.yaml references the file by path:

  contextInjection:
    injectInto: [list_issues, search_issues, get_issue]
    textFile: ./linear-context.md # next to config.yaml

  Relative paths resolve against the lens's directory, so a lens that ships with context.md next to its config.yaml works no matter where the operator launches JanuScope from. Absolute paths and ~/... paths also work.

The operator can run a separate cron job that regenerates linear-context.md every hour (or on commits, or whenever they want); JanuScope picks up the new content the next time the proxy starts. JanuScope itself doesn't fetch from Linear; that decoupling is deliberate so the same overlay works for any lens without baking API integrations into the core.

The runtime path is identical to step 4-6 above: on the next tools/list response, JanuScope appends (or prepends, with position: prepend) the text to the description of every tool listed in injectInto.

When to use which

• Use dbSchema for any lens whose target is Postgres / MySQL / SQLite. JanuScope handles the introspection.
• Use contextInjection for non-DB lenses where you have a small, stable surface the LLM otherwise has to discover. Good fits: Linear (projects / teams / status enums), Atlassian (projects / spaces), filesystem (directory skeleton for a tight allowed root), Notion (workspace navigation skeleton). Marginal fits: Stripe (mostly direct-by-id usage), GitHub (mostly direct-by-id usage). Bad fits: anything large (full file content, full activity feeds) or volatile (real-time issue counts, recent messages).
• Both can run on the same lens, they're independent. A lens against a DB-backed SaaS could use dbSchema for the SQL tool and contextInjection to add a glossary of enum values to a separate non-SQL tool.

Because JanuScope is a stdio proxy spawned as a child of your MCP client, its lifecycle is the client's lifecycle, there is no daemon and no /health endpoint. That is deliberate: no port, no persistent state, nothing for an attacker to reach. It also means the usual process-supervisor patterns don't apply directly. Here's the shape of the failure modes and what to do:

• Unhandled error inside a JanuScope overlay. The engine installs scoped unhandledRejection and uncaughtException handlers for the duration of runOverlay(). Before Node exits, a single structured line lands on stderr:

  [januscope:runtime] 2026-04-20T… error: unhandledRejection {"message":"…","stack":"…"}
  

  Your client will see a broken pipe and surface "MCP server disconnected." The diagnostic line is how you tell which side died, without it you'd be guessing between JanuScope, the wrapped MCP, and the client itself.

• The wrapped MCP crashes or hangs. The stdio transport escalates in three stages, t+2s SIGTERM, t+5s SIGKILL, t+10s give up, and logs at every stage. JanuScope exits cleanly after the child is confirmed dead or the deadline hits. Your MCP client reconnects on the next request and a fresh JanuScope + child MCP pair spawns.

• Stream errors (client stdin / target stdout). Logged as warn and the pipeline closes gracefully. The done promise resolves; runtime exits with code 0.

• Running JanuScope under a supervisor. If you embed JanuScope in a long-running sidecar (e.g. a custom gateway that keeps one stdio bridge per LLM session), supervise it the same way you would any Node process: systemd with Restart=on-failure, or Docker's restart: unless-stopped. The stderr lines above give the supervisor enough to distinguish crashes from clean exits.

• No /health, on purpose. A stdio-only proxy that added an HTTP health endpoint would defeat the "no open listeners" posture. For liveness the right check is: send a tools/list JSON-RPC line and wait for a response, or rely on the client's own connection state.

Native HTTP transport and a richer supervisory story are in the plans; until then, stdio + structured stderr + MCP-client reconnect is the complete loop.

When a lens enables audit:, JanuScope writes a structured JSONL log, one JSON object per line, recording every event that flowed through the proxy. The log is the definitive answer to "what did the AI actually try to do yesterday."

audit:
  sink: ~/mcp-audit-postgres.jsonl # file path, or "stdout" / "stderr"
  logRawArgs: false # default; true = include un-hashed arguments

• ~ expands to your home directory.
• Parent directories are auto-created if they don't exist.
• New sink files are opened with mode 0o600 (user-read/write only). Existing files keep their current mode, if you later flip logRawArgs: true, rotate to a fresh sink so the tighter perms apply.
• stdout / stderr stream JSON lines to the respective pipe instead of a file, useful for forwarding to a log aggregator (januscope --config x.yaml | jq -r …).

Every record has these base fields:

Plus event-specific fields:

startup, written once when the pipeline initialises:

{ "ts": "2026-04-18T12:00:00.000Z", "event": "startup", "sink": "~/mcp-audit.jsonl" }

tools/call, written when a tools/call request is received AND when the target's response arrives (two lines per call, linked by id):

// Request line (written on client → target)
{"ts":"2026-04-18T12:00:01.123Z","event":"tools/call","tool":"query","id":42,"args_hash":"a1b2…"}
// Response line (written on target → client)
{"ts":"2026-04-18T12:00:01.456Z","event":"tools/call","tool":"query","id":42,"status":"ok","result_bytes":2048}

Fields:

JanuScope reads three optional environment variables at startup and stamps them on every audit record:

Each field is omitted from the record when its env var is unset or empty, so the JSONL stays minimal in the single-operator workstation case. Library embedders can override the env capture by passing identity: { user, team, session } to createAuditOverlay() directly.

This is the lightweight identity option for JanuScope. It does NOT do SSO, OIDC, RBAC, or per-call authorisation; the host process supplies the labels out-of-band, and the audit log carries them through to your SIEM. Use it to answer "who ran this query?" / "which CI job?" / "which Claude Code session?" without standing up an identity broker.

shutdown, written when the pipeline tears down cleanly:

{ "ts": "2026-04-18T12:15:00.000Z", "event": "shutdown" }

The full event union is available in two forms, both shipped with the package, so SIEM ingesters don't have to re-transcribe the shape from this README:

• TypeScript: import the AuditEvent union (plus per-event types) from the package entry point:

  import type {
    AuditEvent,
    AuditToolsCallOkEvent,
    AuditToolsCallErrorEvent,
    AuditStartupEvent,
    AuditShutdownEvent,
  } from "januscope";

• JSON Schema (Draft 2020-12): validate every JSONL line before parsing:

  # node_modules/januscope/schemas/audit-event.json, or mirror it in your pipeline.
  ajv --spec=draft2020 validate -s schemas/audit-event.json -d my-audit.jsonl

The two are kept in sync by construction, the TS types are source-of-truth in src/overlays/audit.ts and the JSON Schema mirrors them line-for-line.

By default args_hash is emitted and args is not. This lets you detect repeated identical calls (replay, retry loops) and correlate requests across sessions without the log file itself becoming a liability, raw SQL, request bodies, and file contents never hit disk. Flip logRawArgs: true only in environments where the audit file is already treated as sensitive (dedicated log host, encrypted volume, SIEM pipeline).

Simple tail:

tail -f ~/mcp-audit-postgres.jsonl | jq

Every tools/call that failed at the MCP layer in the last 100 events:

tail -n 100 ~/mcp-audit-postgres.jsonl | jq 'select(.status == "tool_error" or .status == "error")'

All unique tools the model tried to call, ranked by frequency:

jq -r 'select(.event == "tools/call" and .status == null) | .tool' ~/mcp-audit-postgres.jsonl \
  | sort | uniq -c | sort -rn

Request-response pairs joined by id:

jq -c 'select(.event == "tools/call")' ~/mcp-audit-postgres.jsonl \
  | awk -F'"id":' '{print $2}' | sort | uniq -c

If you register audit first in your pipeline (the recommended shape, all bundled Lenses do), it sees the pre-redaction client message and the pre-redaction target response. The client receives the redacted version. This is deliberate: the audit log is the ground-truth record for incident response, while the model never sees raw PII.

# Recommended overlay order
audit: # sees raw bytes, logs pre-redaction
  sink: ~/audit.jsonl
  logRawArgs: true
block: # blocks dangerous tools
  - drop_table
sqlGuard: # blocks dangerous SQL
  tools: [query]
instructions: |
  STRICT POLICY. …
redact: # LAST: scrubs before the model sees anything
  rules:
    - field: "**.email"

JanuScope does not rotate the log itself. If you point sink: at a path, use logrotate (Linux) or a newsyslog rule (macOS) with the standard create 0600 <user> directive so rotated files inherit the right mode. Or stream to stdout and let your log aggregator handle retention.

For tests or embedding in a custom gateway:

import { runOverlay, loadConfig } from "januscope";

const config = loadConfig("./policy.yaml");
await runOverlay({ config });

The runOverlay promise resolves when both the client and the target streams have closed. See src/index.ts for the full public surface.

Claude Skills (the new first-party Anthropic pattern) and JanuScope solve related but different problems. They compose; they do not compete.

Skills shape intent. JanuScope enforces limits. Any serious deployment needs both, that's trust + verify architecture.

What happens if the LLM tries to bypass JanuScope by running redis-cli / psql / gh from the terminal? Nothing JanuScope can stop directly, the terminal is a sibling tool surface in the agent host (Copilot, Cursor, Claude Code), not a wrapped MCP. The proxy only sees JSON-RPC traffic to the MCP it spawned. This is by design and documented in SECURITY.md under the three-layer model:

1. Hide: block removes write tools from tools/list so the model never sees them. The model can't call a tool it doesn't know exists. JanuScope provides this.
2. Advise: instructions (with position: prepend) and contextInjection push a SURFACE BOUNDARY paragraph into the descriptions the model reads, explicitly forbidding terminal / vendor-CLI / sibling-MCP bypass. JanuScope provides this. It is advice, not enforcement, observed live against VS Code Copilot, the model receives the policy text and can recite it when asked, yet still proposes terminal bypasses on its own initiative for some prompts.
3. Enforce at the data path: a credential that physically cannot mutate, configured upstream of JanuScope (read-only DB role, read-only Upstash token, fine-grained read-only PAT, Stripe rk_*). JanuScope cannot provide this layer. It is the actual barrier when layers 1 and 2 do not hold.

For demo / non-production use, layers 1 and 2 alone are usually enough, your data is throwaway, the agent is supervised. For production deployments, layer 3 is mandatory. Each bundled lens README has a Prerequisites section documenting the recommended layer-3 credential for that backend; treat it as a deployment requirement, not a suggestion.

Does this work with remote MCP servers? Yes, today, through the bundled linear-remote, notion-official, and atlassian-official lenses. Each spawns mcp-remote as a stdio↔HTTPS bridge in front of the vendor's Streamable HTTP endpoint (and handles the OAuth flow); JanuScope wraps the bridge as if it were any other stdio MCP. Native Streamable HTTP transport inside JanuScope (no mcp-remote hop) is planned for a post-v0.3 release. See "What is mcp-remote..." below for the install + auth details.

How big is the performance overhead? In-process per-call overhead is sub-millisecond. Measured on Node 22 / M2 with npm run bench:overhead (a 10,000-iteration microbenchmark over the full Pipeline, audit sink pointed at a temp file) the numbers fall around:

So even on the busiest configuration the pipeline itself costs tens of microseconds per request, four to five orders of magnitude below a typical LLM round-trip, and noise against the MCP child-process IO. dbSchema is excluded from the per-cycle table because its only per-request work is the tools/list rewrite (runs once per session); its setup cost is ~50–300 ms of live DB introspection at startup. Run npm run bench:overhead -- --json to get a machine-readable snapshot on your own hardware.

When do I use redact.rules: regex vs field? Use both for serious lenses. field rules target column/property names (**.email, **.password, users[*].stripe_id) and auto-parse JSON strings inside text content blocks, so they catch PII in the rows a SQL MCP returns. regex rules catch value patterns that aren't tied to a column name, email addresses in free-form text, bcrypt hash prefixes, Stripe/AWS key formats. The two are complementary: field rules are more precise, regex rules are more permissive.

block vs sqlGuard, when does each apply? block filters at tool-name granularity, use it when the target MCP exposes write-capable tools as separate tools (e.g. write_query, create_table, drop_table). You block the whole tool. sqlGuard operates one level deeper: when an MCP has a single tool like query or execute_sql that accepts arbitrary SQL, block can't distinguish SELECT from UPDATE through that tool, sqlGuard inspects the SQL argument and rejects anything with write keywords. A serious lens often uses both: block on the obviously-named write tools, sqlGuard on the generic SQL tool.

Is sqlGuard a real SQL parser? No, it's a keyword match after comment stripping and string-literal blanking. That's enough to stop casual LLM-generated writes, which is the threat model. A motivated adversary can craft queries that escape it. For high-assurance use, also give the MCP a database user that is physically read-only at the RDBMS level. Defence in depth.

What specifically does sqlGuard NOT catch? Three documented classes:

1. User-defined functions whose name starts with a DML verb fragment, e.g. SELECT schema.delete_all() or SELECT purge_audits(). JavaScript's \b treats _ as a word character, so \bDELETE\b doesn't match inside delete_all. Same class as SELECT dropUsers(). Tracking these would need a real SQL parser + function catalogue lookup, which is out of scope for a proxy layer.
2. Non-function-call mutation paths we haven't listed. The default allowlist blocks the 17 Postgres admin / filesystem / DoS functions we know about (lo_import, lo_export, pg_read_file, pg_write_file, pg_sleep, pg_terminate_backend, dblink*, COPY … PROGRAM, etc.) but new dangerous functions in future Postgres versions are undetected until the list is updated.
3. Dynamic SQL. If your tool accepts an argument that is then itself SQL-concatenated server-side (usually a design smell, but it happens), sqlGuard only sees the outer tool argument.

Backstop: a database-level read-only role is the last line of defence. sqlGuard is a convenience gate that catches the 95% case without requiring a DB role change; treat it as one layer, not the only one.

Does audit chmod existing files when I enable logRawArgs? No, JanuScope opens new audit sink files with mode 0o600 (user-read/write only), but it does not chmod files that already exist. If your audit log was first created while logRawArgs: false (hashed args only) and you later flip to logRawArgs: true, the old permission bits carry over. Rotate to a fresh sink path when you enable raw-args logging so the tighter 0o600 is applied from day one.

What about TypeScript / Python MCPs? JanuScope doesn't care what language the target MCP is written in, it communicates over stdio JSON-RPC, which is the MCP protocol. The target can be Node, Python, Go, Rust, anything.

Can I use it programmatically without the CLI? Yes, import runOverlay from the library. The CLI is just a thin wrapper around it.

How do I find out what tools my MCP exposes? Run the MCP once with a single tools/list request:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | <your-mcp-command>

The response lists every tool's name, description, and input schema. Use those names in your JanuScope config.

Is there a Windows build? Yes, JanuScope is pure Node.js. DB drivers are optional peer deps. Runs on macOS, Linux, Windows.

What Node version? Node 20+.

What is mcp-remote and do I need to install it? Three bundled Lenses (atlassian-official, notion-official, linear-remote) wrap remote MCPs, vendor-hosted services that speak HTTPS instead of stdio. JanuScope v0.3's engine is stdio-native, so those Lenses spawn mcp-remote (an external npm package by @geelen) as a subprocess via npx -y mcp-remote <url>. mcp-remote is a thin stdio↔HTTPS bridge that also handles the OAuth flow. You don't install it manually, npx fetches and caches it on first use, and the tokens live in ~/.mcp-auth/. Native Streamable HTTP transport inside JanuScope is planned for a post-v0.3 release, which will remove the bridge hop.

JanuScope is dual-licensed:

• Open-source: GNU AGPL-3.0-only. Free for personal use, internal company use, and open-source projects that are also AGPL-compatible. The AGPL's copyleft applies to network-facing deployments, so if you host a modified JanuScope behind an HTTP surface you must publish your modifications.
• Commercial: LICENSE-COMMERCIAL. Drops the AGPL copyleft for commercial redistribution, closed-source forks, or SaaS/OEM offerings. Contact giancarlo@altaire.com for pricing.

Third-party software included in this repository retains its own license, see THIRD-PARTY-LICENSES.

Contributing: please read CONTRIBUTING.md and sign the CLA. The CLA is necessary because of the dual-licensing model.

Copyright © 2026 Giancarlo Erra, Altaire Limited.