Hashnet MCP JS

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