Start free trial

Python licensing library: license keys, site license files and MCP tools, checked offline

carcha-seal is the Carcha Seal SDK for Python. On a computer it activates a license key once and validates a signed lease at every start, with or without a network. In a container or behind an air gap it verifies a signed site license file instead, gates the tools of an MCP server by feature and counts usage into signed reports. It runs the license client in a native library, the same one the C++ and .NET SDKs use.

Reading time
5 min
Updated
15 November 2026
Sections
7
On this page
Install and requirementsCheck at every start, activate onceSite license filesMCP tools gated by the licenseUsage reportsWhat the SDK checksWhat it does not do

Install and requirements

pip install carcha-seal            # the client and site licenses
pip install "carcha-seal[mcp]"     # and the MCP gate (MCP Python SDK 2.x)
Packagecarcha-seal on PyPI
Python3.11 and later
PlatformsWindows x64, macOS 11 and later (Apple Silicon, Intel), Linux with glibc 2.28 and later (x86_64, aarch64). One wheel per platform, the native library inside. Not yet: Alpine (musl), Windows on Arm
DependenciesNone. The mcp extra adds the MCP Python SDK
NetworkThrough urllib: certificates checked, the system or environment proxy, redirects refused; or your own transport
ThreadsOne operation at a time per client; calls from several threads wait for each other

On an Intel Mac, install the MCP extra from wheels only: pip install --only-binary=:all: "carcha-seal[mcp]". The MCP SDK depends on the cryptography package, whose newest versions have no wheel for Intel macOS (15 November 2026); without the option pip builds it from source, which fails without a Rust toolchain.

Check at every start, activate once

For software installed on a computer. Your server address, product code and public keys (the current and the next, so the signing key can rotate without an app update) are on the console's Integrate page.

from carcha_seal import LicenseStatus, SealClient

client = SealClient(
    product="example-studio",
    server_url="https://licenses.example.com",
    public_keys=PUBLIC_KEYS,      # the current and next key, in your code
    storage_dir=app_data_dir,     # license.dat is kept here
    app_version="2.4.0",
)

state = client.check()            # at every start; offline from the saved lease
if state.status is LicenseStatus.UNLICENSED:
    state = client.activate(key_the_user_typed)
if state.has_feature("export-pdf"):
    export_pdf()
activate(key, machine_name=None)Takes a seat, stores the lease. No machine name is sent unless you pass one.
check()Checks in and stores the new lease; offline, decides from the stored one.
deactivate()Frees the seat and deletes the lease.
offline_request(key), activate_offline(file), deactivate_offline()Activation by file, for a computer with no network.
decrypt(feature, data)Opens data encrypted for a feature, offline. The content key stays in the native library.
state.has_feature(name)True only for VALID and GRACE states that include the feature.

Errors are a LicenseError with a code. A saved license that is there and cannot be read is status invalid with the reason storage_unreadable, not "no license"; entering the key again replaces it. States and error codes are the same as in the other SDKs: documentation.

Site license files

Inside a container or a Kubernetes pod a device fingerprint is not stable, so activation on a device does not fit. You issue a site license file in the console (License, Site license file) for a deployment instead. It is bound to no device: whoever holds the file holds the license, so it always expires and cannot be revoked before then. It enforces the term and the features offline; how many copies run is a contract term.

from carcha_seal import SiteLicenseFile

lic = SiteLicenseFile(
    "/etc/seal/license.json",     # the Secret, mounted as a directory (not with subPath)
    product="example-studio",
    public_keys=PUBLIC_KEYS,
    state_dir="/var/lib/studio",  # optional: a floor against a clock set back
)
site = lic.check()                # raises LicenseError: "no_license", "expired", "clock_rolled_back", ...
if site.has_feature("pro"):
    ...

check() reads the file again when it changes, so a renewed Kubernetes Secret needs no restart. A Secret mounted with subPath never receives updates, so mount the directory. verify_site_license(text, ...) verifies a file's text once.

MCP tools gated by the license

carcha_seal.mcp.LicenseGate is a middleware for MCP servers built on the official MCP Python SDK. Each gated tool names the feature of the site license it needs.

from mcp.server.mcpserver import MCPServer
from mcp.server.subscriptions import InMemorySubscriptionBus
from carcha_seal.mcp import LicenseGate

gate = LicenseGate(lic, tools={"search_documents": "tools.search", "export_report": "pro"}, free={"ping"})
bus = InMemorySubscriptionBus()
mcp = MCPServer("studio", middleware=[gate], subscriptions=bus)
# run gate.watch(bus) alongside the server (its lifespan or task group)
  • The list. tools/list shows only the tools the license grants, and the free ones.
  • The call. A call to a tool the license does not grant returns a tool result with isError: true and a text the model can read. It is checked on every call, not only in the list.
  • Renewal and expiry. watch(bus) checks the license every 30 seconds; when the usable features change, clients are told that the tool list changed.
  • New tools. A tool you did not map is refused, so a tool added later is not given away by forgetting it.

The tool set depends only on the license, never on the connection, as the MCP specification requires of tools/list. The guide has the reasoning: Licensing an MCP server that runs air-gapped.

Usage reports

Where nothing can call home, carcha_seal.usage.UsageLog counts calls per tool and outcome, writes them once per period as records that each name the SHA-256 of the record before, and exports a signed report your customer sends you. You upload it in the console (License, Usage reports), which checks it and adds what it counts.

from carcha_seal.usage import UsageLog

usage = UsageLog("/var/lib/studio/usage")           # one folder per running copy
gate = LicenseGate(lic, tools=TOOLS, usage=usage)
...
report = usage.export(lic.check())                  # the records since the last export, signed

The console refuses a report that was changed after it was signed, and shows records missing between two reports. A report proves the counts were not changed after they were written, not that every call was counted: whoever runs the software holds the key.

What the SDK checks

  • The signature. A lease and a site license file are compact JWS signed with Ed25519; your code holds only public keys, chosen by key id.
  • The computer. A lease names a hash of the operating system's machine ID and the product code; the raw ID never leaves the computer. A site license file names no computer.
  • Time. Expiry, the end of updates, the check-in deadline and grace; a clock turned back by more than a day is reported as clock_suspect. A site license file always has an end date.
  • Features. Only features listed in the lease or the file are granted, and data encrypted for a feature opens only with a lease that includes it.

What it does not do

  • Stop someone who controls the computer. A check in your code can be patched out. Data encrypted for a feature, opened with decrypt, is what a patched app is missing.
  • Count copies of a site license. The file is bound to no device and cannot be revoked before it expires; the number of copies is a contract term.
  • Feature decryption under a site license. A site license file carries no feature keys; decrypt needs a license activated on a device.
  • Floating seats. They are in the C++, .NET and Electron SDKs, not yet in this package.

Sources

Checked on 15 November 2026 against the published package and the documentation.

License your app in an afternoon.

14-day trial, no card. Your own server address and signing key from the first minute.