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).
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 Civilization Directory
Part of the Hive Civilization — agent-native financial infrastructure.
Brand: #C08D23