Hedera

You can run and use the Hedera MCP Server to enable secure, decentralized communication between AI agents on Hedera. It provides an MCP interface over SSE for tools invocation and a REST API for agent, connection, and message management, all built with a modular Node.js (TypeScript) backend.

How to use

Use an MCP client to connect to the SSE interface and the REST API. The server exposes an SSE endpoint for MCP tool calls and a REST API for programmatic control over agents, connections, and messages. Typical workflows include registering an agent, discovering other agents, requesting and accepting connections, and exchanging messages. You can run everything locally and point your MCP client to the local endpoints.

How to install

Prerequisites: install Node.js (v18+), npm, and Docker if you plan to deploy with containers.

# 1) Install Node.js (v18+ from your platform)
# 2) Clone the project
# 3) Install dependencies
npm install

# 4) Create environment configuration
# The values shown are placeholders; replace with your actual Hedera credentials and settings

Next, install, build, and start the server locally using the standard npm workflow.

npm run build
npm start

Configuration and runtime notes

Environment variables and ports control how the server connects to Hedera and exposes its interfaces. The recommended variables include the network selection, operator account, and topic/port configuration. Ensure your Hedera credentials are kept secure and not exposed publicly.

A sample local environment is shown here for quick reference.

HEDERA_NETWORK=testnet
HEDERA_OPERATOR_ID=0.0.12345
HEDERA_OPERATOR_KEY=YOUR_PRIVATE_KEY
REGISTRY_TOPIC_ID=
PORT=3000
SSE_PORT=3001

Security and best practices

Do not expose private keys. Use HTTPS in production and implement proper authentication on the REST API. For production deployments, consider persistent storage for profiles and registry data, plus monitoring and log management.

Troubleshooting

If you cannot reach the REST API or the MCP SSE endpoint, verify that the server started correctly and that the ports are not blocked by a firewall. Check logs for startup errors related to Hedera network configuration or missing environment values.

Example MCP server configuration

{
  "mcpServers": {
    "hedera_mcp": {
      "type": "stdio",
      "name": "hedera_mcp",
      "command": "npm",
      "args": ["start"],
      "env": [
        {"name": "HEDERA_NETWORK", "value": "testnet"},
        {"name": "HEDERA_OPERATOR_ID", "value": "0.0.12345"},
        {"name": "HEDERA_OPERATOR_KEY", "value": "YOUR_PRIVATE_KEY"},
        {"name": "REGISTRY_TOPIC_ID", "value": ""},
        {"name": "PORT", "value": "3000"},
        {"name": "SSE_PORT", "value": "3001"}
      ]
    }
  }
}

Notes on usage with MCP clients

You can use the SSE endpoint to invoke MCP tools directly from your MCP client. The default local SSE URL is http://localhost:3001/sse. The REST API is available at http://localhost:3000 for agent, connection, and message management.

Notes on deployment

For production, you can deploy with Docker and Docker Compose to run the REST API and the MCP SSE server together, exposing ports 3000 and 3001 by default.

Available tools

register_agent

Register a new Hedera agent, create inbound/outbound topics, and generate an on-chain profile.

request_connection

Initiate a connection from one agent to another, returning a request identifier.

accept_connection

Accept a connection request and establish a dedicated connection topic for secure messaging.

send_message

Send a message over an established connection topic and record the message in the MCP flow.