Why tool plans break in an air gap
The common way to sell MCP tools by plan is an entitlement check at request time: the server, or a gateway in front of it, asks the vendor's billing service whether this customer's plan includes the tool. That works on the internet. In a bank, a hospital or a defense site the server runs inside the customer's network and nothing can reach the vendor.
GitLab's issue 587846 describes the result. GitLab's MCP server endpoint requires Duo Core, and Duo Core requires a connection to GitLab's cloud-connected AI Gateway. The use cases listed include an air-gapped government contractor and a regulated financial institution, and the issue asks for the MCP server to work without that connection.
The MCP specification does not define licensing. Its authorization chapter covers OAuth over HTTP and says that servers on the stdio transport should take their credentials from the environment instead. A license, then, is something the server reads from its own environment: a file it can verify by itself.
What the specification lets a license change
The 2026-07-28 revision of the tools chapter sets the rules a license-driven tool list has to follow:
- The list may change, but not per connection. A server returns the tools currently available; the set may change over time and may vary by the authorization on the request, but must not vary per connection. A tool list that depends only on the installation's license fits.
- Clients may cache the list. A
tools/listresult can carry a cache lifetime,ttlMs. A lifetime longer than the license would keep showing tools after it ends. - Change notices reach only listeners. On 2026-07-28 a client hears
notifications/tools/list_changedonly if it opened asubscriptions/listenstream for it. - A refusal should be a tool result. Business-logic errors are returned as a result with
isError: true, which clients should pass to the model so it can react. A protocol error tells the model much less.
The official Python SDK adds one more fact: its low-level Server forwards a tools/call for a name it never listed straight into the handler,
and any exception raised there becomes a protocol error, never an isError result. Together these rules decide the design: hide unlicensed tools from the
list as a courtesy to the model, but check every call, and answer a refused call with an isError result.
The license: a signed file bound to no machine
A license bound to a device fingerprint does not fit a container: the fingerprint inside a pod is not stable. Carcha Seal issues a site license file
for a deployment instead, from the license's page in the console or POST /api/licenses/:id/site-license. It is an Ed25519-signed token with the
license's features, the deployment's name and an end date, and the SDK verifies it with your public key and no network.
Because it is bound to no machine, whoever holds the file holds the license. So a site license always expires (at most a year and a day, never after the license itself), cannot be revoked before then, and carries no feature keys. How many copies run stays in your contract.
In Kubernetes, put the file in a Secret and mount the Secret as a directory. Kubernetes updates a mounted Secret in place, eventually (the kubelet sync period
plus cache delay), but a container that mounts it with subPath receives no updates at all. The SDK re-reads the file when it changes, so a renewal
reaches a running server without a restart; renew a few days before the old file ends.
Gating the tools
In the Python SDK, LicenseGate is a middleware for MCP servers on the official MCP Python SDK. Each gated tool names the feature it needs:
from mcp.server.mcpserver import MCPServer
from mcp.server.subscriptions import InMemorySubscriptionBus
from carcha_seal import SiteLicenseFile
from carcha_seal.mcp import LicenseGate
license = SiteLicenseFile("/etc/seal/license.json", product="studio", public_keys=PUBLIC_KEYS)
gate = LicenseGate(license, tools={"search_documents": "tools.search", "export_report": "pro"}, free={"ping"})
bus = InMemorySubscriptionBus()
server = MCPServer("studio", middleware=[gate], subscriptions=bus)
# run gate.watch(bus) next to the server
- The list shows only the tools the license grants and the free ones, and a cache lifetime is cut to the license's end.
- A call to a tool the license does not grant returns
isError: truewith a sentence the model can act on (it should not retry and should tell the user) and a machine-readable reason under_meta:feature_not_licensed,license_expiredand the like. - A tool you forgot to map is refused, so adding a tool to the server does not give it away.
- A renewal or an expiry is announced once: to 2026-07-28 clients through
subscriptions/listen, and to older clients on their connection. A client that never listens is still refused at the call.
These behaviours are tested in process with the MCP SDK's own client, over a stdio subprocess, and on both protocol eras, including a model that keeps calling a tool after it was removed and calls racing a renewal.
Counting usage without telemetry
Usage pricing in an air gap usually means a report the customer writes by hand, backed by contract. Most such reports carry nothing a vendor can check;
Reprise RLM is one of the few products that authenticates its report logs. Carcha Seal's UsageLog counts each tool call (completed, failed or
refused) and writes the counts once an hour as a record that names the record before it by its SHA-256. An export signs the records with a key the deployment made
for itself.
The customer sends you the file and you upload it on the license's page. The console refuses a report that was changed after it was signed or whose records were changed, removed or reordered. It also checks the report against the last one from the same key: it shows records missing in between, refuses to count a report that contradicts one already received, and marks a new key for a deployment, which is what deleting the usage folder gives. A record is counted once, even when an export is sent twice.
A report proves the counts were not changed after they were written. It does not prove every call was counted: the deployment holds its own key. It makes the contract checkable, not unbreakable.
What this cannot do
- Revoke before the end date. An offline file works until it expires. Short terms and regular renewals keep that window small.
- Count copies. A file bound to no machine can be copied. Usage reports show each running copy's key; enforcing a number of copies needs seats from a server the copies can reach.
- Trust the clock. Keygen says that no offline-only solution against clock tampering is fully effective. The SDK refuses a clock set back before the license's issue time and, with a state folder, before a time it already saw; whoever controls the machine can reset that folder too.
- Stop someone who edits the server. The gate runs in your code on the customer's hardware. What is protected is what the license controls: the vendor-side features, the term and the counts.
- Cover every SDK yet. Site license files, the MCP gate and usage reports are in the Python SDK. The C++, .NET and Electron SDKs verify leases but not site license files yet.
Air-gapped software monetization · Offline license verification · Try the live demo
Sources
Each page was checked on 15 November 2026.
- GitLab, issue 587846: MCP Server without the cloud-connected AI Gateway
- Model Context Protocol, specification 2026-07-28: Tools
- Model Context Protocol, specification 2026-07-28: Authorization
- MCP Python SDK, low-level server
- Kubernetes, Secrets
- Keygen, security (offline clock tampering)
- Reprise RLM, report log format