hashnet-mcp-js

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