hive-mcp-vault

MCP access to confirmed HiveVault FENR reads and an AES-256-GCM encrypted item store.

Live contract

The server exposes four read-only MCP tools backed by the live HiveVault service:

Tool	Live backend route
`vault.balance`	`GET /vault/balance`
`vault.stats`	`GET /vault/stats`
`vault.identity`	`GET /vault/identity`
`vault.quantum_pubkey`	`GET /vault/quantum/pubkey`

vault.balance returns the backend response exactly as received. An unauthenticated response can be marked obfuscated: true; clients must not treat that value as a confirmed treasury balance.

The server also exposes an encrypted item store:

Method	Path	Description
`POST`	`/v1/vault/store`	Store an AES-256-GCM encrypted item after the x402 gate
`GET`	`/v1/vault/store/:item_ref`	Confirm a stored item exists without returning plaintext

Unknown paths return HTTP 404. Upstream failures return explicit MCP errors. The service does not return fabricated success payloads.

Discovery and health

Method	Path	Description
`GET`	`/health`	Readiness. This process plus current upstream reachability. Returns 503 and `degraded` when the upstream is unreachable
`GET`	`/livez`	Liveness only. This process, no upstream claim. This is the path platform health checks should use
`POST`	`/mcp`	MCP JSON-RPC 2.0, protocol `2024-11-05`
`GET`	`/.well-known/mcp.json`	MCP discovery manifest
`GET`	`/.well-known/agent-card.json`	A2A agent card
`GET`	`/.well-known/agent.json`	Agent card
`GET`	`/.well-known/oac.json`	Open Agent Card JSON-LD
`GET`	`/llms.txt`	Plain-text integration guide

Persistence

Set BOGO_DB_PATH to a path on durable storage in production. The default path, /tmp/bogo_vault.db, is suitable only for local development and tests. The server refuses to start in production unless an explicit database path is configured.

Environment variables

Variable	Required	Purpose
`PORT`	No, default `3000`	HTTP port
`VAULT_BACKEND_URL`	No, default `https://hive-vault.onrender.com`	Live HiveVault backend
`INTERNAL_KEY`	Yes in production	Derives the local encryption key and is sent to the backend as `x-vault-key`
`BOGO_DB_PATH`	Yes in production	SQLite database path on durable storage. Local development defaults to `/tmp/bogo_vault.db`
`BASE_RPC_URL`	No, default `https://mainnet.base.org`	Base RPC endpoint used for x402 payment verification

The server refuses to start with NODE_ENV=production if INTERNAL_KEY or BOGO_DB_PATH is missing.

Testing

npm install
npm test

Tests cover health reporting, unknown-route handling, MCP tool discovery, upstream failure behavior, encrypted storage, and plaintext absence from the SQLite file.

Brand

Hive Civilization. Brand gold #C08D23. Steve Rotzin.

Hive Vault