Skip to main content

sevenmaps-guard

MCP client middleware for Python. Before your client calls an MCP server, sevenmaps_guard asks 7Maps about it: is the server down, and (if you pass the date a person approved it) did its tools get riskier since then. It blocks the call only in those two cases. If you switch telemetry on, it also reports how each tool call went (ok or failed, and how long it took), which keeps the shared map accurate for every agent that reads it.

Install

pip install sevenmaps-guard

Python 3.9 or later. Standard library only (urllib, json, threading). The official mcp package is needed only for guarded_call.

Usage

from mcp import ClientSession
from sevenmaps_guard import guarded_call, GuardError

URL = "https://mcp.example.com/mcp"

async def search(session: ClientSession):
    try:
        return await guarded_call(session, URL, "search", {"q": "invoices"},
                                  approved_at="2026-09-01", telemetry=True)
    except GuardError as e:
        print("blocked:", e.verdict["reason"])

guarded_call(session, server_url, tool, args):

  • runs guard() (cached, in a worker thread so the event loop is not blocked) and raises GuardError (with .verdict) on deny;
  • times session.call_tool(tool, args) and, with telemetry on, reports ok, or failed with one of: timeout, auth (401/403), rate_limited (429), args (invalid params), unreachable (connection error), server_error (anything else). A result with is_error / isError set is reported as not ok, without a reason. Exceptions are re-raised unchanged.
  • Extra keyword arguments go to call_tool. check=False skips the guard.

Works with mcp 1.x and 2.x.

Check only

from sevenmaps_guard import guard, report

v = guard("https://mcp.example.com/mcp", approved_at="2026-09-01")
# {'allow': True, 'reason': 'status open; since 2026-09-01: unchanged', 'condition': {...}, 'watch': {...}}
if not v["allow"]:
    raise SystemExit(v["reason"])

report("https://mcp.example.com/mcp", ok=False, tool="search", fail="timeout", ms=30000)

guard(server_url, approved_at=None, cache_seconds=600, *, license_key=None, timeout=5.0) never raises. It denies only when 7Maps reports the server down, or when watch reports risk_increased since approved_at. condition is the structuredContent of 7Maps road_conditions; watch is the structuredContent of watch, or None.

report(...) sends on a background daemon thread and returns the thread at once; the request is abandoned after 3 seconds.

Cost

road_conditions answers the first 20 calls a day per agent without charge, then asks for $0.002 per call via x402. watch is paid per call ($0.005). The Python package does not pay x402; a paid answer counts as "7Maps unavailable": the verdict falls back to allow (or, for watch, the change check is skipped and the reason says change check: 7maps unavailable). A 7IT monthly plan license_key is passed through if you have one. The in-memory cache keeps the number of calls low. report_road is not charged.

CLI

The command-line check ships with the Node.js package:

npx 7maps-guard check https://mcp.example.com/mcp --approved 2026-09-01

Exit code 0 for allow, 2 for deny.

What is sent

Every request goes to https://7it.co.il/7maps/mcp?via=guard as an MCP tools/call over HTTPS, with the header user-agent: 7maps-guard/<version> (+https://github.com/XLSV777/7maps). Like any HTTPS request, it also carries your IP address. No cookies, no account, no device ID.

The server address is reduced to scheme, host and path before it is sent: the query string, the fragment and any user:password@ part are removed, since they can carry keys. Path segments that look like keys or tokens (20 or more characters with both letters and digits, or starting with sk_, pk_, rk_ or ak_) are replaced by *. Even so, keep secrets out of server paths: put them in a header.

Call When Fields
road_conditions every guard() / guarded_call() not served from cache server (and license_key if you set one)
watch only when approved_at is set server, approved_at (and license_key)
report_road only with telemetry on (guarded_call), or when you call report() server, tool (the tool name), ok, fail (one of the values above, only when not ok), ms (whole milliseconds)

Never sent: tool arguments, tool results, prompts, model output, your server's headers or tokens, environment variables, host names of your machines, or anything else.

Telemetry is opt-in. guarded_call reports only with telemetry=True, or when the environment variable SEVENMAPS_TELEMETRY=1 is set. telemetry=False always wins. SEVENMAPS_TELEMETRY=0 turns off every report, including direct report() calls. With telemetry off, the checks still work.

Why report

7Maps checks every remote server in the official MCP registry once a day with a handshake. That says whether a server answers, not whether its tools work for real callers. Reports from agents fill that gap: every report makes the shared map more accurate for everyone, and the rating every agent sees comes from them. They also help 7Maps spot a server that starts failing; an incident is shown once 7Maps confirms it. Each agent's reports on one server count only up to a daily limit.

Fail-open guarantee

If 7Maps cannot be reached, times out, is rate limited, returns something unexpected, or asks for payment, guard() returns {"allow": True, "reason": "7maps unavailable", "condition": None, "watch": None}. guard() never raises. report() never raises and never blocks the caller. A problem on the 7Maps side never blocks your work.

MIT license.

Metadata

Release files for sevenmaps-guard 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sevenmaps-guard 0.1.1
File Size Uploaded Provenance Actions
sevenmaps_guard-0.1.1.tar.gz 10.7 kB With provenance Details for sevenmaps_guard-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sevenmaps-guard 0.1.1
File Interpreter ABI Platform Actions
sevenmaps_guard-0.1.1-py3-none-any.whl Python 3 none any Details for sevenmaps_guard-0.1.1-py3-none-any.whl

Total release size: 20.3 kB

Release files / sevenmaps_guard-0.1.1.tar.gz

Download URL sevenmaps_guard-0.1.1.tar.gz
Size 10.7 kB
Tags Source
SHA-256 checksum
How to use checksums
03a1f3eecf681d3a5684985222165c25da8929efd2a4adb6db5bc7b659a1e1af
BLAKE2b-256 checksum
How to use checksums
21cd66e2c59cbede223671ff264f9821dd24612dfc8543655d805b30f670d22e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / sevenmaps_guard-0.1.1-py3-none-any.whl

Download URL sevenmaps_guard-0.1.1-py3-none-any.whl
Size 9.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4cd8a4753f952967ebfc88ca7f21fa673ce024d28c98c56954cc4f9f7a0e2bcb
BLAKE2b-256 checksum
How to use checksums
73d3bb37d420f1aefca0a9662f1d498b3ed46a12d69da4504d9516a7383c65a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for sevenmaps-guard 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sevenmaps_guard-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page