hashgraph-online/hashnet-mcp-js

npm version npm downloads Node version Bundle size Publish Canary License CodeSandbox

Universal MCP server for discovery, chat, registration, credits, and workflow automation across the HOL Registry Broker ecosystem.

Ecosystem

Surface	Link
npm package	@hol-org/hashnet-mcp
GitHub repo	hashgraph-online/hashnet-mcp-js
GitHub releases	Releases
Documentation	hol.org/mcp
CodeSandbox	Open examples in browser

Quickstart

pnpm install
cp .env.example .env
pnpm dev:http

Common launch modes:

• pnpm dev:stdio
• pnpm dev:http
• pnpm dev:http:compat
• npx @hol-org/hashnet-mcp --help
• npx @hol-org/hashnet-mcp --stdio
• npx @hol-org/hashnet-mcp --http --host 127.0.0.1 --port 3333

When installed globally or linked locally, the binary is hashnet-mcp.

Supported Transports

Transport	Endpoint(s)	Notes
stdio	process stdin/stdout	best for local agent runtimes
Streamable HTTP	/mcp, /mcp/stream	recommended HTTP transport
legacy HTTP + SSE	/mcp/sse, /mcp/messages	enabled with FEATURE_LEGACY_SSE=1

Runtime utility endpoints:

• /healthz
• /readyz
• /metrics

Tool Surface

• Discovery: hol.stats, hol.capabilities, hol.search, hol.vectorSearch, hol.resolveUaid
• Chat: hol.chat.readiness, hol.chat.createSession, hol.chat.sendMessage, hol.chat.retry, hol.chat.history, hol.chat.resume, hol.chat.end
• Registration: hol.getRegistrationQuote, hol.registerAgent, hol.waitForRegistrationCompletion
• Workflows: workflow.discovery, workflow.delegate, workflow.registration

Tool success responses use structured envelopes in structuredContent:

• ok
• data
• meta

Tool failures return isError: true with structured machine-readable error fields (code, category, retryable).

Configuration

Variable	Required	Notes
REGISTRY_BROKER_API_URL	no	defaults to https://hol.org/registry/api/v1
REGISTRY_BROKER_API_KEY	no	enables paid tools with a static broker API key
BROKER_REQUEST_TIMEOUT_MS	no	default upstream request timeout is 60000
MCP_TRANSPORT	no	http (default) or stdio
MCP_HOST	no	defaults to 127.0.0.1
MCP_PORT	no	defaults to 3333
MCP_ALLOWED_ORIGINS	no	comma-separated allow list
MCP_SERVER_BEARER_TOKEN	no	required when binding to a non-local host (for example 0.0.0.0)
MCP_SESSION_IDLE_TTL_MS	no	defaults to 900000
MCP_SESSION_MAX_COUNT	no	defaults to 250
MCP_SESSION_REAP_INTERVAL_MS	no	defaults to 60000
LEDGER_ACCOUNT_ID	no	generic ledger identity fallback
HEDERA_ACCOUNT_ID	no	Hedera account id
HEDERA_NETWORK	no	e.g. hedera:testnet
HEDERA_PRIVATE_KEY	no	Hedera private key
EVM_LEDGER_NETWORK	no	e.g. eip155:1
ETH_PK	no	EVM private key

Security Defaults

• Binds to 127.0.0.1 by default.
• Validates Origin for HTTP requests when present.
• Enforces bearer-token auth when binding to non-local hosts.
• Reaps idle HTTP sessions and enforces max active sessions.
• Redacts sensitive values in logs.

Development

Command	Purpose
pnpm build	compile distributable artifacts
pnpm start	run compiled server
pnpm lint	run ESLint
pnpm typecheck	run TypeScript checks
pnpm test:run	run Vitest once
pnpm test:coverage	run Vitest with coverage
pnpm check:no-stubs	enforce no-stubs contract
pnpm smoke:http	streamable HTTP smoke test
pnpm smoke:stdio	stdio smoke test

Release Notes Automation

GitHub releases are generated automatically from merged pull requests:

• release tags are created during publish (vX.Y.Z)
• GitHub release notes are generated with GitHub's release-note engine
• changelog categories are controlled via .github/release.yml
• canonical docs links are appended to each release