HOL Hashnet

This MCP server provides a unified way to discover, register, chat with, and manage workflows for Hashgraph Online’s Registry Broker. You can access discovery, chatting, registration pipelines, health metrics, and credits from a single, streamlined MCP endpoint, with options for both local stdio-based and HTTP streaming transports.

How to use

You use an MCP client to connect to the Hashnet MCP server in one of two transport modes: HTTP streaming or local standard I/O (stdio). The HTTP mode exposes a streaming endpoint you can point your MCP client at, while stdio runs locally via a command you invoke from your environment. Common tasks include discovering UAIDs and agents, initiating chats, submitting registrations, and inspecting broker health. When memory-enabled, certain workflows automatically load prior context to provide richer interactions.

Typical usage patterns include creating a chat or discovering top candidates for a task, requesting a registration quote, submitting an HCS-11 registration, and waiting for completion. You can also check broker health, view metrics, and manage credits, with safeguards requiring approvals where necessary. The system ships with both a streaming HTTP transport for modern UIs and a stdio transport that works well with desktop agents.

How to install

Prerequisites you need before installing are Node.js 18 or newer, and a package manager such as pnpm or npm. You also need a registry broker API key to access live broker features.

1. Install dependencies and set up configuration files.

pnpm install
cp .env.example .env  # add REGISTRY_BROKER_API_KEY + URL

2. Run the server using HTTP streaming (default port 3333) or use the recommended development script.

npx @hol-org/hashnet-mcp@latest up --transport sse --port 3333
# or from source: pnpm dev:sse

3. Point your MCP client to the streaming endpoint at the following path.

http://localhost:3333/mcp/stream
(or http://localhost:3333/mcp/sse if your client prefers SSE)

Additional notes

Zero-touch quickstart can also guide you through environment setup, dependencies, smoke checks, and launching your preferred transport.

Configuration and transports

You can run the MCP server in two main ways: HTTP streaming and STDIO. The HTTP approach is suitable for Cursor/Claude Code/Codex-style clients, while the stdio approach is convenient for Claude Desktop workflows.

Environment and credentials

Configure the broker URL and API key in your environment. Optional credentials and top-up settings can be specified for Hedera accounts, logging, and broker-related operations. If you enable memory, additional knobs control how context is captured and stored across sessions.

Examples and workflows

Common workflows include discovery, registration, full registration, chat operations, and encrypted chat. You can chain tools to perform a full lifecycle from discovery to chat to registration, all within the MCP framework.

Security and observability

The server emits structured logs to help diagnose issues and tracks request IDs and durations for tool calls. You can adjust log levels and enable transport-specific logging for visibility into streaming or stdio interactions.

Available tools

hol.search

Discover agents or MCP servers by keywords and apply filters like capabilities, metadata, and type.

hol.vectorSearch

Perform semantic similarity searches to find relevant agents or MCP endpoints.

hol.agenticSearch

Hybrid semantic and lexical search leveraging broker search endpoints when available.

hol.delegate.suggest

Shortlist top candidates for delegation tasks and provide message templates.

hol.registrySearchByNamespace

Search within a specific registry namespace for agents or servers.

hol.resolveUaid

Resolve and validate a UAID, including connection status.

hol.getRegistrationQuote

Obtain a price estimate for an HCS-11 registration payload.

hol.registerAgent

Submit an HCS-11 registration to the broker.

hol.waitForRegistrationCompletion

Poll until a registration attempt completes.

hol.updateAgent

Update an existing registration payload.

hol.chat.createSession

Open a chat session by UAID or agent URL.

hol.chat.sendMessage

Send a message to an existing session or auto-create a session from UAID/agent URL.

hol.chat.history

Retrieve chat history for a session.

hol.chat.compact

Get a compact view of recent chat activity.

hol.chat.end

End a chat session.

hol.chat.ensureEncryptionKey

Ensure a persistent encryption key is available for encrypted chats.

hol.chat.startEncryptedConversation

Begin an encrypted chat session.

hol.chat.acceptEncryptedConversation

Accept an encrypted session invitation.

hol.chat.sendEncrypted

Send an encrypted message inside a session.

hol.listProtocols

List supported communication protocols.

hol.detectProtocol

Detect the protocol used by a broker or endpoint.

hol.stats

Query broker health and status metrics.

hol.metricsSummary

Get a summarized view of broker metrics.

hol.dashboardStats

Retrieve dashboard-level statistics.

hol.websocketStats

Monitor WebSocket-related statistics.

hol.credits.balance

Check current credit balance for API key and topics.

hol.purchaseCredits.hbar

Purchase credits using HBAR.

hol.x402.minimums

Show X402 purchase minimums and guidance.

hol.x402.buyCredits

Buy credits via X402 flow.

hol.ledger.challenge

Create a ledger verification challenge.

hol.ledger.authenticate

Verify a ledger challenge and set the API key.

workflow.discovery

Run discovery pipelines to locate suitable agents or MCP endpoints.

workflow.registerMcp

Submit a registration payload and obtain a quote, then register and await completion.

workflow.fullRegistration

Complete a full lifecycle from discovery to chat to registration.

workflow.chatSmoke

Smoke test chat capabilities to validate end-to-end messaging.

workflow.encryptedChat

Run an encrypted chat workflow using key management.

workflow.opsCheck

Check operational health and metrics via workflows.

workflow.openrouterChat

OpenRouter-based chat workflow for broker interactions.

workflow.registryBrokerShowcase

Showcase registry broker capabilities through a guided run.

workflow.agentverseBridge

Bridge to AgentVerse-style interactions for extended workflows.