Network MCP Server

Overview

The Hedera Network Hosted MCP Server provides a managed, remote instance of the Hedera Agent Kit exposing its tools via the [Model Context Protocol (MCP). Any MCP-compatible client that supports OAuth 2.1 — such as Claude, Cursor, Codex CLI, ChatGPT Desktop, or a custom AI application — can now use the Hedera network.

The Hedera Network MCP is non-custodial and on Testnet only The server holds no Hedera keys of any kind, never submits a transaction, and never sees your signature. It builds and freezes transactions, then delivers them to your wallet. Your wallet signs and sends it to the network.

Claude CLI Quickstart

Make sure you have a testnet account set up (get one in the Developer Portal), and a Hedera compatible wallet (like HashPack or Kabila).
Start your AI agent and add the MCP.

claude mcp add --transport http hedera-testnet-mcp https://agentic-testnet-mcp.hedera.com/mcp

Restart Claude, then use the command /mcp to find & authenticate the MCP.
Connect your web3 wallet (get the HashPack or Kabila browser extension or mobile app).
Try your first Hedera transaction within your AI agent.
Sign and send your transaction from your AI agent with your web3 wallet.

Setup

Adding the Hedera Network MCP works the same way as adding any other remote MCP server to your AI tool. You only need the server URL:

https://agentic-testnet-mcp.hedera.com/mcp

There is no account ID, API key, or header to configure. Your Hedera account is proven by your wallet when you sign in. Before you start, you need:

A Hedera testnet account. Create one for free in the Developer Portal.
A Hedera-compatible wallet with that account loaded, such as HashPack or Kabila, as a browser extension or mobile app.

Add the MCP to your AI tool

Claude Desktop

Go to Settings → Connectors → Add custom connector.
Enter the details:
- Name: Hedera-Testnet
- URL: https://agentic-testnet-mcp.hedera.com/mcp
Under Authentication, choose Required when the server asks or Always required. Either option works.
Under OAuth client, choose No client ID — register one automatically.
Leave Additional request headers and Advanced untouched, then click Add.
A browser window opens with the Hedera sign-in page. Follow the steps in Authenticate your wallet, then try the example prompts.

Claude (Web & Mobile)

Custom connectors are available on free, Pro, Max, Team, and Enterprise plans (free users are limited to one custom connector).

Navigate to Customize → Connectors (or go directly to https://claude.ai/new#settings/customize-connectors).
Click Add in the top right corner, then select Add custom connector.
Enter the details:
- Name: Hedera-Testnet
- URL: https://agentic-testnet-mcp.hedera.com/mcp
Under Authentication, choose Required when the server asks or Always required. Either option works.
Under OAuth client, choose No client ID — register one automatically.
Leave Additional request headers and Advanced untouched, then click Add.
A browser window opens with the Hedera sign-in page. Follow the steps in Authenticate your wallet.
In any chat, click the + button in the lower left of the chat interface, then hover over Connectors to enable Hedera for that conversation. Then try the example prompts.

Connectors added on claude.ai are also available in Claude Desktop and Claude mobile when signed in with the same account, and vice versa. You do not need to add the server separately in each.

Cursor

Cursor supports MCP servers through its mcp.json configuration file.Steps:

Open Cursor Desktop app and navigate to Customize tab.
Select MCPs and click the Add button. This opens an editor with the mcp.json file. Add the following entry, then save (Cmd+S / Ctrl+S):

{
  "mcpServers": {
    "hedera": {
      "url": "https://agentic-testnet-mcp.hedera.com/mcp"
    }
  }
}

Navigate back to the MCPs list and click Authenticate next to the Hedera entry.
Cursor opens a browser with the Hedera sign-in page. Follow the steps in Authenticate your wallet, then try the example prompts.

VS Code

VS Code supports MCP servers through the Chat view’s MCP settings.Steps:

Open the Chat tab in VS Code.
Click the gear icon in the Chat tab to open chat customization.
Select MCP Servers, then click Add Server.
Select HTTP.
Enter the server URL: https://agentic-testnet-mcp.hedera.com/mcp.
Set the name to hedera-testnet and confirm.
A popup about required authentication appears. Click Allow. A second popup asks to open an external website. Click Open.
You are taken to the Hedera sign-in page. Follow the steps in Authenticate your wallet, then try the example prompts.

Claude Code CLI

Run the following command in your terminal:

claude mcp add --transport http hedera-testnet https://agentic-testnet-mcp.hedera.com/mcp

Start Claude Code and run:

/mcp

Select the hedera server and choose Authenticate. Your browser opens the Hedera sign-in page. Follow the steps in Authenticate your wallet, then try the example prompts.
Verify the connection:

claude mcp list

You should see hedera listed as ✔ Connected.

If your wallet session ends (for example, you disconnect the Hedera MCP session in your wallet), run claude mcp logout hedera, then /mcp → Authenticate to sign in again.

Codex CLI

Run the following command in your terminal:

codex mcp add hedera-testnet --url https://agentic-testnet-mcp.hedera.com/mcp

Codex opens the Hedera sign-in page automatically. Follow the steps in Authenticate your wallet, then try the example prompts.
Verify the connection:

codex mcp list

If your wallet session ends, run codex mcp login hedera to sign in again.

Devin CLI

Run the following command in your terminal:

devin mcp add hedera-testnet https://agentic-testnet-mcp.hedera.com/mcp

Ask Devin to authenticate:

Please authenticate the hedera mcp

Your browser opens the Hedera sign-in page. Follow the steps in Authenticate your wallet, then try the example prompts.

ChatGPT Desktop

Go to Settings → Plugins, then open the MCPs tab.
Click Add in the top right corner and select Add MCP server.
Enter the details:
- Name: hedera-testnet
- Type: streamable HTTP
- URL: https://agentic-testnet-mcp.hedera.com/mcp
Leave the remaining settings as they are, then confirm.
In the MCPs tab, find the new entry and click Authenticate. Your browser opens the Hedera sign-in page. Follow the steps in Authenticate your wallet.
Restart the app and open a chat in the Work tab to use the server. Then try the example prompts.

MCP servers are only accessible from the Work tab. The normal chat tab cannot reach them.

Authenticate your wallet

Instead of a username and password, you sign in to the Hedera Network MCP with your wallet. This proves you own the Hedera account without sharing any keys with the server.

After adding the MCP, your AI tool opens a Hedera sign-in page in your browser.
You may see a page asking you to confirm that you started this connection from your AI tool. This is expected. Continue.
Connect your wallet: scan the WalletConnect QR code with your mobile wallet, or click the browser extension button if you have one installed.
Your wallet asks you to approve a sign-in message. Approving it moves no funds. It only proves you control the account.
Return to your AI tool. It is now connected to your Hedera account and ready to use.

You only need to do this once. The session stays active until it expires or you disconnect it in your wallet. See Troubleshooting if you need to sign in again.

Example prompts

Read-only requests return results immediately and do not involve your wallet:

What's my HBAR balance?

Show me the latest messages on topic 0.0.12345

Requests that change network state build a transaction and send it to your wallet. Approve it in your wallet to submit it to the network:

Create a topic with memo "test"

Send 1 HBAR to 0.0.98765

Create a fungible token called "Demo Token" with symbol DEMO and 1000 initial supply

What you can do with Hedera Network MCP

The Hedera Network MCP includes all core Hedera plugins from the Hedera Agent Kit. Through your AI tool you can:

Area	Capabilities
Accounts	Create accounts, update keys, transfer HBAR, manage allowances, check balances
Tokens (HTS)	Create, mint, transfer, associate, and look up fungible and non-fungible tokens
Smart Contracts (EVM)	Deploy, call, and query ERC-20 and ERC-721 contracts
Consensus (HCS)	Create topics, submit messages, and read topic info
Transactions & Network	Look up transaction records, exchange rates, and node fees

See the Plugins page for the complete list of tools and their parameters.

Wallet tools

The server also includes tools for managing your wallet connection. Your AI tool uses these automatically, but you can ask about them directly.

Tool	What it does
`wallet_status`	Shows which account and network you are connected to, and when the session expires
`check_signing_status`	Checks whether a transaction you sent to your wallet has been approved, rejected, or confirmed
`sign_with_wallet`	Sends raw transaction bytes to your wallet. Rarely needed, since transaction tools deliver to your wallet automatically

Not every transaction type is fully readable in a wallet. Smart contract calls and file operations cannot be fully decoded by your wallet, so its display is not an independent check of what the transaction does. Review what your AI tool tells you it is building before approving.

Troubleshooting

“The connector’s server isn’t responding” or “Couldn’t connect to the server”

This almost always means your wallet session has ended, not that the server is down. For example, you removed the session from your wallet, or the session expired.
Your AI tool does not prompt you to reconnect on its own, and restarting it does not clear the old session.
Fix: open your AI tool’s MCP or connector settings, find the Hedera entry, Disconnect, then Connect again and complete the wallet sign-in.

Removed the session in your wallet and now nothing works

Disconnecting the session in your wallet (for example, removing the dApp from HashPack) also ends the session on the server. Reconnect the MCP as described above.

Reconnected but never asked to sign in again

If a valid wallet session still exists, it is reused automatically. This is expected.

A transaction came back as expired

You have about 180 seconds to approve a transaction in your wallet. If it lapses, ask your AI tool to run the action again.

Tools not appearing after connecting

Restart your AI tool after adding or reconnecting the server.

Limitations

Testnet only. The hosted server does not connect to mainnet. Run the self-hosted Hedera Agent Kit MCP server for mainnet.
Single-key accounts only. Threshold and key-list accounts are not supported for wallet sign-in.
No spend policies. There are no per-transaction or per-day caps or recipient allowlists. Your wallet approval prompt is the spending control, so review each request.

Developer Information

This section covers the authentication and transaction model in more detail for developers building MCP clients or integrating the server into custom applications.

The signing model has changed. Transactions are now approved and signed in the user’s own wallet. The server no longer returns transaction bytes for the client to sign. The x-hedera-account-id header is no longer used and is ignored; the account now comes from the wallet sign-in. The endpoint URL is unchanged, but existing connections must sign in again with a wallet before any tool will work.

Authentication

The server is an OAuth 2.1 authorization server whose login form is a wallet. It supports Dynamic Client Registration, so clients do not need a pre-registered client ID.

The client’s first tool call is rejected with 401, which triggers the standard OAuth authorization flow.
The client opens a browser to the server’s sign-in page. An interstitial may ask the user to confirm they started the connection from their MCP client.
The user pairs a wallet via WalletConnect (QR code or browser extension).
The wallet prompts the user to sign a sign-in message: a single-use, domain-bound nonce. No transaction is created.
The server verifies the signature against the account’s key on the mirror node and issues an access token scoped to that account.

The server never holds keys, never submits transactions, and never sees a transaction signature.

Transaction lifecycle

Every transaction tool (transferring HBAR, creating a topic, minting a token, and so on) builds the transaction, freezes it, and delivers it to the user’s wallet for approval in one call. It returns a requestId instead of blocking. The agent then polls for the outcome:

transfer_hbar_tool({ to, amount })   ->  { requestId, summary, walletVerifiable, ... }
check_signing_status({ requestId })  ->  awaiting_approval | confirming | executed | ...

Status	Meaning
`awaiting_approval`	Delivered to the wallet; waiting on user approval
`confirming`	The wallet broadcast it; the server is checking the mirror node
`executed`	Confirmed on the mirror node
`rejected`	The user declined it in the wallet
`failed`	Reached the network but failed on-chain
`expired`	The ~180 second validity window lapsed
`needs_reauth`	The wallet session ended; the client must re-authenticate

executed means the mirror node confirmed the transaction, not just that the wallet reported a broadcast, so a stale approval that never lands is reported honestly rather than as a false success. The ~180 second window matches Hedera’s transaction validity window.

Wallet verifiability

Each write tool response includes a walletVerifiable flag. It is true when the wallet can fully decode and display the transaction contents (HBAR transfers, token operations, topic operations). It is false for contract calls and file operations, where the wallet’s display is not an independent check of what the transaction does. Surface the tool’s summary to the user in these cases.

Session handling

Wallet sessions are established via WalletConnect. If the user removes the dApp session from their wallet, the server-side session ends and tools return needs_reauth.
Clients do not currently receive a proactive re-authentication prompt. Users must disconnect and reconnect the server (or run the client’s logout/login command) to start a new wallet sign-in.
If a valid wallet session exists when the client reconnects, it is reused without a new wallet prompt.

Self-hosting

The hosted server is testnet only. To run against mainnet or customize the toolset, run the Hedera Agent Kit MCP server yourself.

Overview

Tokenization

AI & Agents

Governance

Sustainability

Developer Tools

Examples

Network MCP Server

Overview

Claude CLI Quickstart

Setup

Add the MCP to your AI tool

Authenticate your wallet

Example prompts

What you can do with Hedera Network MCP

Wallet tools

Troubleshooting

Limitations

Developer Information

Authentication

Transaction lifecycle

Wallet verifiability

Session handling

Self-hosting

​Overview

​Claude CLI Quickstart

​Setup

​Add the MCP to your AI tool

​Authenticate your wallet

​Example prompts

​What you can do with Hedera Network MCP

​Wallet tools

​Troubleshooting

​Limitations

​Developer Information

​Authentication

​Transaction lifecycle

​Wallet verifiability

​Session handling

​Self-hosting

Overview

Claude CLI Quickstart

Setup

Add the MCP to your AI tool

Authenticate your wallet

Example prompts

What you can do with Hedera Network MCP

Wallet tools

Troubleshooting

Limitations

Developer Information

Authentication

Transaction lifecycle

Wallet verifiability

Session handling

Self-hosting