MCP Implementation in Hathor Forge

In addition to providing a local blockchain development environment, Hathor Forge also exposes a Model Context Protocol (MCP) server to connect to your AI model's instance.

This integration allows you to leverage AI in your development workflow, making it easier to ask questions about your code, jump start blueprint development, and even generate use cases based on your queries, allowing the AI to control the environment programmatically.

Prerequisites

Before connecting an AI assistant to the Hathor Forge MCP server, make sure you have:

• Hathor Forge installed and able to run. See Running Hathor Forge for the three installation methods.
• An MCP-capable AI client. The examples below use Claude Code, but any client that supports the Model Context Protocol over HTTP will work.
• The MCP server port available (default: 9876). Hathor Forge starts the MCP server automatically when you run it with --start.

:::info What is MCP?

The Model Context Protocol is an open standard that lets AI assistants call external tools. By exposing an MCP server, Hathor Forge allows your AI client to start the node, create wallets, fund addresses, and query the blockchain on your behalf — without you writing the API calls yourself.

:::

Claude Code

As an example, you could set it up with Claude Code by running the following command in your terminal:

# Terminal 1: start Hathor Forge
nix run github:HathorNetwork/hathor-forge -- --start

# Terminal 2: register the MCP server
claude mcp add --transport http hathor-forge http://127.0.0.1:9876/mcp

tip

Make sure to replace the URL with the correct one if your MCP server is running on a different address or port.

The MCP server address and port are configured in the Settings panel of the Hathor Forge desktop app, or via the --mcp-port CLI flag (default: 9876). See Running Hathor Forge for the full list of CLI flags.

:::info Transport

The Hathor Forge MCP server is exposed over streamable HTTP at /mcp. Configure your client for the HTTP transport (as shown above); other MCP transports such as stdio are not used here.

:::

Or you can simply add the following snippet to your project's .mcp.json:

{
  "mcpServers": {
    "hathor-forge": {
      "type": "http",
      "url": "http://127.0.0.1:9876/mcp"
    }
  }
}

Available Tools

Category	Tools
Node	start_node, stop_node, get_node_status
Miner	start_miner, stop_miner, get_miner_status
Wallet Service	start_wallet_service, stop_wallet_service, get_wallet_service_status
Wallets	generate_seed, create_wallet, get_wallet_seed, get_wallet_status, get_wallet_balance, get_wallet_addresses, send_from_wallet, close_wallet
Faucet	get_faucet_balance, send_from_faucet, fund_wallet
Blockchain	get_blocks, get_transaction
Quick Actions	quick_start, quick_stop, get_full_status, reset_data

Example Use Case

The following is an illustrative exchange — it shows the shape of an interaction, not literal tool output. Actual responses are structured MCP tool-call results that your client renders in its own format.

You: "Start the blockchain and create a test wallet with 50 HTR"

Claude: [Uses quick_start, create_wallet, fund_wallet]
        "Done! Node running at block 45, miner active.
         Created wallet 'test' with 50 HTR."

Verifying the connection

After registering the server, confirm the client can see it before relying on AI-assisted workflows.

With Claude Code, list registered MCP servers:

claude mcp list

hathor-forge should appear as connected. You can also check the endpoint is reachable directly:

curl http://127.0.0.1:9876/mcp

A running server responds (an MCP handshake error from a plain curl is expected and still confirms reachability); a connection refused means Hathor Forge is not running or is on a different port.

Troubleshooting

• Client shows the server as failed or disconnected. Hathor Forge must be running before the client connects. Start it (nix run github:HathorNetwork/hathor-forge -- --start) and confirm the MCP server line appears in its output, then restart or re-register the server in your client.
• Connection refused on port 9876. Either Forge is not running, or the MCP server is on a different port. Check the port in the Settings panel or the --mcp-port flag and update the URL in your client config to match.
• Tools appear but every call fails. The MCP server is reachable but the underlying services are not started. Ask the AI to run quick_start (or start the node/miner/wallet service from the Forge UI) before invoking wallet or blockchain tools.

:::warning Local development only

The MCP server can programmatically control wallets and move funds in your local environment. Keep it bound to 127.0.0.1 and never expose it on a public network interface.

:::