hive-mcp-cdn

Edge cache for A2A capabilities — Hive Civilization

A small, inbound-only MCP server that caches arbitrary objects (agent cards, capability manifests, signed envelopes, anything an A2A pipeline reads more than once). Two-tier storage with an in-memory LRU and a SQLite warm tier, ETag and If-None-Match support, a purge endpoint, and per-request and per-GB metering through x402.

Council provenance: Ad-hoc, user-promoted 2026-04-27.

What this is

Most A2A traffic is reads — the same agent card, the same capability list, the same signed proof — fanned out across a fleet that has no shared cache. hive-mcp-cdn is the missing edge cache. Agents put objects under a key and fetch them back through a cheap, ETag-aware GET.

Protocol: MCP 2024-11-05 over Streamable-HTTP / JSON-RPC 2.0
Transport: POST /mcp
Discovery: GET /.well-known/mcp.json
Health: GET /health
Settlement: USDC on Base L2
Brand gold: Pantone 1245 C / #C08D23
Mode: Inbound only. ENABLE=true default.

Pricing

Surface	Price	Charged on
Per request	$0.0002 USDC	Every `/v1/cdn/get`, hit or miss.
Per GB egress	$0.05 USDC	Body bytes returned in `200` responses. `304` responses do not bill egress.
Prepay bundle	$1.00 USDC	Buys an access token; reads draw from the prepaid balance until depletion.

Settlement on Base L2 USDC. The recipient is the WALLET_ADDRESS env var.

Tools

Tool	Tier	Description
`cdn_cache_get`	2 ($0.0002/req + $0.05/GB)	Read a cached object by key. Honors `if_none_match`.
`cdn_cache_put`	0 (free)	Store under a key with optional `Cache-Control: max-age=...`.
`cdn_purge`	0 (free)	Purge a single key. Idempotent.

REST endpoints

Method	Path	Purpose
`GET`	`/v1/cdn/get?key=...`	Read. Sends `ETag`, `Cache-Control`, `X-Cache`, `Age`. Honors `If-None-Match`.
`POST`	`/v1/cdn/put`	Write `{ key, body, content_type?, cache_control? }`.
`POST`	`/v1/cdn/purge`	Purge `{ key }`.
`GET`	`/v1/cdn/today`	Daily counters: requests, hits, misses, bytes served, revenue.
`POST`	`/v1/x402/proof/submit`	Submit on-chain proof, mint access token.
`GET`	`/v1/x402/pricing`	Pricing schedule.
`GET`	`/v1/x402/stats`	Open nonces and active tokens.
`GET`	`/health`	Service health and cache stats.
`GET`	`/.well-known/mcp.json`	MCP discovery descriptor.
`GET`	`/`	Landing page.

Storage model

Two tiers, both managed by the shim:

Hot (LRU): an in-process Map with insertion-order recency. Bounded by CDN_LRU_MAX_ENTRIES and CDN_LRU_MAX_BYTES. Misses fall through to warm and promote on read.
Warm (SQLite): better-sqlite3 at CDN_DB_PATH (default /tmp/cdn.db). One cache table with body, ETag, content type, size in bytes, created and expiry timestamps. A second egress table aggregates daily counters.

size_bytes is tracked per row and is the basis for the egress meter. ETags are computed once at write time as the SHA-256 hex of the body, truncated to 32 chars and double-quoted.

x402 flow

The first call to /v1/cdn/get without a token returns:

{
  "error": "payment_required",
  "payment": {
    "nonce": "<uuid>",
    "amount_usd": 1.0,
    "pricing": {
      "per_request_usd": 0.0002,
      "per_gb_egress_usd": 0.05
    },
    "accepts": [{ "chain": "base", "asset": "USDC", "recipient": "0x15184b..." }],
    "expires_at": 1777220000,
    "tier": 2,
    "product": "cdn_prepaid_bundle"
  }
}

Submit proof to /v1/x402/proof/submit:

{ "nonce": "...", "payer": "0x...", "chain": "base", "tx_hash": "0x..." }

…then call /v1/cdn/get with X-Hive-Access: hive_<token>. Each request decrements the prepaid balance by per_request + (bytes / 1GB) * per_gb_egress. The residual balance rides the X-Hive-Balance-USD response header.

Cache semantics

Cache-Control: max-age=<s> on PUT sets the TTL. Default 300 seconds. Capped at 7 days.
ETag is a strong validator (SHA-256 prefix in quotes).
If-None-Match: <etag> on GET returns 304 Not Modified with no body and no egress charge.
Expired entries are dropped lazily on read and on a 60-second sweep.
A PUT over an existing key replaces the body, ETag, content type, TTL, and resets the hit counter.

Environment

Var	Default	Purpose
`PORT`	`3000`	HTTP port.
`ENABLE`	`true`	Master switch. `false` runs `/health` only.
`WALLET_ADDRESS`	`0x15184bf50b3d3f52b60434f8942b7d52f2eb436e`	Recipient for x402 fees.
`CDN_PRICE_PER_REQUEST_USD`	`0.0002`	Per-request fee.
`CDN_PRICE_PER_GB_EGRESS_USD`	`0.05`	Per-GB egress fee.
`CDN_PREPAY_BUNDLE_USD`	`1.0`	Default prepay bundle size.
`CDN_DEFAULT_TTL_S`	`300`	Default TTL for objects without explicit `max-age`.
`CDN_LRU_MAX_ENTRIES`	`1024`	Hot-tier entry cap.
`CDN_LRU_MAX_BYTES`	`67108864`	Hot-tier byte cap (64 MiB).
`CDN_MAX_OBJECT_BYTES`	`4194304`	Per-object size limit (4 MiB).
`CDN_DB_PATH`	`/tmp/cdn.db`	SQLite warm-tier path.

What this server will not do

Make outbound requests of any kind. The cache only holds what was put into it.
Resolve URLs, fetch origins, or revalidate against a backing store.
Enforce per-key access control. Treat keys as opaque namespaces and gate them upstream if you need privacy.
Persist beyond the SQLite file. On a fresh container with a new /tmp, the cache is empty.

License

MIT.

Hive Gamification

This MCP server is part of the Hive Civilization gamification surface (10-mechanic capability taxonomy).

Capability taxonomy: https://hive-gamification.onrender.com/.well-known/hive-gamification.json
Centrifuge dashboard: https://hive-gamification.onrender.com/.well-known/hive-centrifuge.json
Consolidated OpenAPI: https://hive-gamification.onrender.com/.well-known/openapi.json

Surface tags: gamification.spec.v1 · gamification.surface.public · gamification.signal.read-only · gamification.settlement.real-rails

Real rails on Base L2 (USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913). Read-only signal layer. Brand gold #C08D23.

Hive Cdn