JanuScope

"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.

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 →

What it looks like in practice

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.

Contents

Quick Start

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

Option A: use a bundled Lens (fastest, drop-in)

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:[email protected]"
  }
}

{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "mongodb-official"],
  "env": {
    "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:[email protected]"
  }
}

{
  "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.

Option B: write your own policy

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.

Why JanuScope

Three problems that hit every real MCP deployment

  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.

Today's options, and what's wrong with them

Option Problem
Fork every MCP server you use and patch it Unmaintainable as the MCP ecosystem moves
Use only the "safe" MCPs Cuts off most useful connectors
Build it yourself per server Each team solves the same problem, each team gets it subtly wrong
Buy a hosted gateway (Composio, Arcade, etc.) You hand your data to a third party; compliance blocks the deal
JanuScope One thin proxy, one YAML, self-hosted, works with any MCP

What makes JanuScope different

  • 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.

"Why not just set --access-mode=restricted on postgres-mcp and call it done?"

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:

What --access-mode=restricted gives you What JanuScope adds on top
Postgres blocks DML at the DB layer audit, every call as JSONL with SHA-256 args hash; compliance-ready without changing the MCP
(that's it) redact, PII scrubbed before the LLM ever sees it, with field-path rules that reach into JSON-in-text envelopes
(that's it) instructions, policy text pushed into every tool description; reduces the social-engineering leak rate we measure in the benchmark
(that's it) dbSchema pre-injection, 84% token reduction, cached across the session
(that's it) sqlGuard, a proxy-layer backstop against bypasses the DB-level role can't catch (UDF-name fragments like SELECT dropUsers(), see below)
Postgres only The same six overlays apply to all 20 bundled lenses (Postgres, MongoDB, MS SQL via DAB, Oracle SQLcl, Snowflake, Aurora DSQL, Redshift, Supabase self-host, Supabase cloud, Neon cloud, MySQL, Redis, ClickHouse, SQLite, Stripe, GitHub, filesystem, Notion, Atlassian, Linear)

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.

What it does

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.

Under the hood: the details that actually work

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?"

Lenses: the community ecosystem

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

Bundled Lenses (20)

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