> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hedera.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Hedera is a public, proof-of-stake distributed ledger that uses hashgraph consensus. Do not call it a blockchain.
> Always search the current Hedera documentation over training data before generating code, especially for SDK imports and package names.
> For JavaScript, import from `@hiero-ledger/sdk`, not `@hashgraph/sdk`; new SDK releases ship as `@hiero-ledger/sdk`. The Java SDK keeps the `com.hedera.hashgraph:sdk` Maven coordinates. Verify the exact import against the docs.
> Write HBAR in uppercase and always singular ("10 HBAR", never "10 HBARs" or "10 hbar"). Write tinybars in lowercase and plural.
> Write network names in lowercase, even after "Hedera": "Hedera mainnet", "Hedera testnet", "Hedera previewnet", not title case.
> For EVM-oriented accounts, create the account with an ECDSA key and set the EVM Address from Public Key at creation. This address is immutable and is not updated by key rotation. Do not use retired terms like "EVM alias" or "Account Number Alias".
# Network MCP Server
> Connect your AI agent to the Hedera Network Hosted MCP Server. Create Hedera transactions and approve them in your own wallet.
## 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
1. Make sure you have a testnet account set up (get one in the [Developer Portal](https://portal.hedera.com/dashboard)), and a Hedera compatible wallet (like [HashPack](https://www.hashpack.app/) or [Kabila](https://kabila.app/docs/kabila-wallet)).
2. Start your AI agent and add the MCP.
```bash theme={null}
claude mcp add --transport http hedera-testnet-mcp https://agentic-testnet-mcp.hedera.com/mcp
```
3. Restart Claude, then use the command `/mcp` to find & authenticate the MCP.
4. Connect your web3 wallet (get the HashPack or Kabila browser extension or mobile app).
5. Try your first Hedera transaction within your AI agent.
6. 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](https://portal.hedera.com/dashboard).
* A Hedera-compatible wallet with that account loaded, such as [HashPack](https://www.hashpack.app/) or [Kabila](https://kabila.app/docs/kabila-wallet), as a browser extension or mobile app.
### Add the MCP to your AI tool
1. Go to **Settings → Connectors → Add custom connector**.
2. Enter the details:
* **Name:** `Hedera-Testnet`
* **URL:** `https://agentic-testnet-mcp.hedera.com/mcp`
3. Under **Authentication**, choose **Required when the server asks** or **Always required**. Either option works.
4. Under **OAuth client**, choose **No client ID — register one automatically**.
5. Leave **Additional request headers** and **Advanced** untouched, then click **Add**.
6. A browser window opens with the Hedera sign-in page. Follow the steps in [Authenticate your wallet](#authenticate-your-wallet), then try the [example prompts](#example-prompts).
Custom connectors are available on free, Pro, Max, Team, and Enterprise plans (free users are limited to one custom connector).
1. Navigate to **Customize → Connectors** (or go directly to [https://claude.ai/new#settings/customize-connectors](https://claude.ai/new#settings/customize-connectors)).
2. Click **Add** in the top right corner, then select **Add custom connector**.
3. Enter the details:
* **Name:** `Hedera-Testnet`
* **URL:** `https://agentic-testnet-mcp.hedera.com/mcp`
4. Under **Authentication**, choose **Required when the server asks** or **Always required**. Either option works.
5. Under **OAuth client**, choose **No client ID — register one automatically**.
6. Leave **Additional request headers** and **Advanced** untouched, then click **Add**.
7. A browser window opens with the Hedera sign-in page. Follow the steps in [Authenticate your wallet](#authenticate-your-wallet).
8. 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](#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 supports MCP servers through its `mcp.json` configuration file.
**Steps:**
1. Open Cursor Desktop app and navigate to `Customize` tab.
2. 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`):
```json theme={null}
{
"mcpServers": {
"hedera": {
"url": "https://agentic-testnet-mcp.hedera.com/mcp"
}
}
}
```
3. Navigate back to the MCPs list and click **Authenticate** next to the Hedera entry.
4. Cursor opens a browser with the Hedera sign-in page. Follow the steps in [Authenticate your wallet](#authenticate-your-wallet), then try the [example prompts](#example-prompts).
VS Code supports MCP servers through the Chat view's MCP settings.
**Steps:**
1. Open the **Chat** tab in VS Code.
2. Click the gear icon in the Chat tab to open chat customization.
3. Select **MCP Servers**, then click **Add Server**.
4. Select **HTTP**.
5. Enter the server URL: `https://agentic-testnet-mcp.hedera.com/mcp`.
6. Set the name to `hedera-testnet` and confirm.
7. A popup about required authentication appears. Click **Allow**. A second popup asks to open an external website. Click **Open**.
8. You are taken to the Hedera sign-in page. Follow the steps in [Authenticate your wallet](#authenticate-your-wallet), then try the [example prompts](#example-prompts).
1. Run the following command in your terminal:
```bash theme={null}
claude mcp add --transport http hedera-testnet https://agentic-testnet-mcp.hedera.com/mcp
```
2. Start Claude Code and run:
```
/mcp
```
3. Select the `hedera` server and choose **Authenticate**. Your browser opens the Hedera sign-in page. Follow the steps in [Authenticate your wallet](#authenticate-your-wallet), then try the [example prompts](#example-prompts).
4. Verify the connection:
```bash theme={null}
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.
1. Run the following command in your terminal:
```bash theme={null}
codex mcp add hedera-testnet --url https://agentic-testnet-mcp.hedera.com/mcp
```
2. Codex opens the Hedera sign-in page automatically. Follow the steps in [Authenticate your wallet](#authenticate-your-wallet), then try the [example prompts](#example-prompts).
3. Verify the connection:
```bash theme={null}
codex mcp list
```
If your wallet session ends, run `codex mcp login hedera` to sign in again.
1. Run the following command in your terminal:
```bash theme={null}
devin mcp add hedera-testnet https://agentic-testnet-mcp.hedera.com/mcp
```
2. Ask Devin to authenticate:
```text theme={null}
Please authenticate the hedera mcp
```
3. Your browser opens the Hedera sign-in page. Follow the steps in [Authenticate your wallet](#authenticate-your-wallet), then try the [example prompts](#example-prompts).
1. Go to **Settings → Plugins**, then open the **MCPs** tab.
2. Click **Add** in the top right corner and select **Add MCP server**.
3. Enter the details:
* **Name:** `hedera-testnet`
* **Type:** streamable HTTP
* **URL:** `https://agentic-testnet-mcp.hedera.com/mcp`
4. Leave the remaining settings as they are, then confirm.
5. 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](#authenticate-your-wallet).
6. Restart the app and open a chat in the **Work** tab to use the server. Then try the [example prompts](#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.
1. After adding the MCP, your AI tool opens a Hedera sign-in page in your browser.
2. You may see a page asking you to confirm that you started this connection from your AI tool. This is expected. Continue.
3. Connect your wallet: scan the WalletConnect QR code with your mobile wallet, or click the browser extension button if you have one installed.
4. Your wallet asks you to approve a **sign-in message**. Approving it moves no funds. It only proves you control the account.
5. 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](#troubleshooting) if you need to sign in again.
## Example prompts
Read-only requests return results immediately and do not involve your wallet:
```text theme={null}
What's my HBAR balance?
```
```text theme={null}
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:
```text theme={null}
Create a topic with memo "test"
```
```text theme={null}
Send 1 HBAR to 0.0.98765
```
```text theme={null}
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](/solutions/ai/agent-kit/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](/solutions/ai/agent-kit/index) 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.
1. The client's first tool call is rejected with `401`, which triggers the standard OAuth authorization flow.
2. 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.
3. The user pairs a wallet via WalletConnect (QR code or browser extension).
4. The wallet prompts the user to sign a **sign-in message**: a single-use, domain-bound nonce. No transaction is created.
5. 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](/solutions/ai/agent-kit/index) MCP server yourself.