From 39e741e356447a75cc471a977a7e97b3d7742110 Mon Sep 17 00:00:00 2001 From: skurzyp-blockydevs Date: Wed, 13 May 2026 13:10:31 +0200 Subject: [PATCH 1/2] docs: add documentation for Hosted MCP Server in Hedera AI Agent Kit - update Hosted MCP Server endpoint and add query/transaction limitations - move mcp docs out of HAK to AI studio root Signed-off-by: skurzyp-blockydevs docs: --- docs.json | 1 + .../hedera-ai-agent-kit.mdx | 8 ++ .../ai-studio-on-hedera/hosted-mcp-server.mdx | 103 ++++++++++++++++++ 3 files changed, 112 insertions(+) create mode 100644 hedera/open-source-solutions/ai-studio-on-hedera/hosted-mcp-server.mdx diff --git a/docs.json b/docs.json index 7b50254c..8b9835d8 100644 --- a/docs.json +++ b/docs.json @@ -479,6 +479,7 @@ "hedera/open-source-solutions/ai-studio-on-hedera", "hedera/open-source-solutions/ai-studio-on-hedera/agent-lab", "hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/elizaos-plugin", + "hedera/open-source-solutions/ai-studio-on-hedera/hosted-mcp-server", { "group": "Hedera AI Agent Kit", "pages": [ diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit.mdx index 476026cb..de0c779b 100644 --- a/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit.mdx +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit.mdx @@ -70,6 +70,14 @@ Both SDKs provide: --- +## Hosted MCP Server + +The **Hashgraph Hosted MCP Server** provides a managed, remote instance of the Hedera Agent Kit exposing its tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). It operates strictly in `RETURN_BYTES` mode. + +[Learn more about the Hosted MCP Server →](/hedera/open-source-solutions/ai-studio-on-hedera/hosted-mcp-server) + +--- + ## SDK Comparison | Feature | JavaScript SDK | Python SDK | diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/hosted-mcp-server.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hosted-mcp-server.mdx new file mode 100644 index 00000000..693cbf74 --- /dev/null +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hosted-mcp-server.mdx @@ -0,0 +1,103 @@ +--- +title: "Hosted MCP Server" +description: "Use the Hashgraph Hosted Model Context Protocol (MCP) server to integrate Hedera Agent Kit tools into your MCP-compatible clients" +sidebarTitle: "Hosted MCP Server" +--- + +## Overview + +The **Hedera Hosted MCP Server** provides a managed, remote instance of the Hedera Agent Kit exposing its tools via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Any MCP-compatible client — such as Cursor, Claude Desktop, or a custom AI application — can integrate Hedera network capabilities without deploying or maintaining local agent infrastructure. + + +**RETURN_BYTES Mode:** The Hosted MCP Server operates exclusively in `RETURN_BYTES` mode. The server will *not* sign or execute transactions on-chain. Every transaction-building tool returns the constructed transaction as hex-encoded bytes, and your client application is responsible for signing and submitting them to the network. + + + +**Network:** The hosted server is connected to **Hedera Testnet only**. For Mainnet integrations, run the [self-hosted MCP server](https://github.com/hashgraph/hedera-agent-kit-js/tree/main/examples/modelcontextprotocol). + + +## Connection Details + +The server uses the MCP Streamable HTTP transport. + +- **Endpoint:** `https://agentic-testnet-mcp.hedera.com/mcp` +- **Transport:** Streamable HTTP +- **Network:** Hedera Testnet + +## Context Initialization + +When connecting to the server, provide your Hedera Account ID via an HTTP header. This initializes the session context so every tool call knows which account to build transactions for. + +- **Header Name:** `x-hedera-account-id` +- **Value:** Your Hedera Testnet Account ID (e.g., `0.0.12345`) + +On the initialize request, the server queries the Hedera Mirror Node to fetch the associated public key and configures the agent's scope for your account. If the account cannot be found on the Mirror Node, the initialize request returns `400` with an explanatory error. + + +Never send private keys to the hosted server. Only your account ID is required — the server constructs unsigned transactions, and signing happens entirely on your side. + + + +**Session Management:** There is no need to manually generate, configure, or export a Session ID (SID) when connecting to the Hosted MCP Server. Standard MCP-compatible clients (like Claude and Cursor) utilize the official Model Context Protocol SDK under the hood, which automatically captures the dynamically generated `mcp-session-id` header from the server's initialization response. The client's transport layer then silently attaches this session header to all subsequent requests in the background, ensuring seamless state persistence without manual intervention. + + +## Client Configuration + +Most MCP-compatible clients accept a JSON configuration block. Register the hosted server as follows: + +```json +{ + "mcpServers": { + "hedera": { + "url": "https://agentic-testnet-mcp.hedera.com/mcp", + "headers": { + "x-hedera-account-id": "0.0.YOUR_ACCOUNT_ID" + } + } + } +} +``` + +Replace `0.0.YOUR_ACCOUNT_ID` with your Hedera Testnet account ID. After updating the configuration, restart your client — the Hedera tools should appear in its tool list. + +> [!WARNING] +> **Read-Only / Query Only for Standard IDEs & GUI Clients:** General-purpose AI clients like **Cursor** and **Claude Desktop** have no built-in capability to sign or submit raw transaction bytes returned by the Hosted MCP Server. +> - **Queries:** These clients can seamlessly perform all read-only queries (e.g., checking account balances, querying token details). +> - **Transactions:** If you ask the client to perform a state-changing transaction (like transferring HBAR or minting tokens), it will return the unsigned, hex-encoded transaction bytes. You will need to manually copy these bytes and sign/submit them using a local script or Hedera SDK. + +### Where to put the config + +- **Cursor:** `~/.cursor/mcp.json` for a global config, or `.cursor/mcp.json` inside a project for per-project tools. +- **Claude Desktop:** `claude_desktop_config.json` — the path depends on your OS; see Anthropic's MCP setup guide. +- **Custom MCP clients:** consult your client's documentation for how to register MCP servers and pass HTTP headers. + +## Working with RETURN_BYTES + +Because the hosted server never signs transactions, every state-changing tool returns a response containing the unsigned, hex-encoded transaction bytes. To complete an operation, your client must: + +1. Receive the hex bytes from the tool response. +2. Decode and sign them using a Hedera SDK with the account's private key. +3. Submit the signed transaction to the Hedera network. + +Read-only queries — balances, token info, transaction records, exchange rates, and similar — return their results directly. No signing is required for those. + +See the [Hedera Agent Kit examples](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/examples/langchain-v1/return-bytes-tool-calling-agent.ts) for examples of signing and submitting transaction bytes. + + +## Available Tools + +The hosted server comes pre-configured with all core Hedera plugins. Exposed tool categories include: + +- **Accounts:** create accounts, update keys, transfer HBAR, manage allowances, query balances. +- **Tokens (HTS):** create, mint, transfer, associate, and query 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 query topic info. +- **Transactions & Misc:** query transaction records, exchange rates, and node fees. + +See the [Plugins](/hedera/open-source-solutions/ai-studio-on-hedera/hedera-ai-agent-kit/plugins) page for the complete list of tools and their parameters. + +## Limitations + +- **Testnet only.** The hosted instance does not connect to Mainnet. Run the self-hosted server for Mainnet usage. +- **No transaction execution.** All state-changing operations require the client to sign and submit. +- **In-memory sessions.** Sessions are not persisted; if the server restarts, active clients need to re-initialize. \ No newline at end of file From ee77e922d380c29fb700cba87040f16d9b4c3285 Mon Sep 17 00:00:00 2001 From: skurzyp-blockydevs Date: Wed, 27 May 2026 09:21:43 +0200 Subject: [PATCH 2/2] docs: clarify usage of Hedera Testnet account ID and transaction signing requirements in Hosted MCP Server documentation Signed-off-by: skurzyp-blockydevs --- .../ai-studio-on-hedera/hosted-mcp-server.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/hedera/open-source-solutions/ai-studio-on-hedera/hosted-mcp-server.mdx b/hedera/open-source-solutions/ai-studio-on-hedera/hosted-mcp-server.mdx index 693cbf74..1c60d6f9 100644 --- a/hedera/open-source-solutions/ai-studio-on-hedera/hosted-mcp-server.mdx +++ b/hedera/open-source-solutions/ai-studio-on-hedera/hosted-mcp-server.mdx @@ -29,7 +29,7 @@ The server uses the MCP Streamable HTTP transport. When connecting to the server, provide your Hedera Account ID via an HTTP header. This initializes the session context so every tool call knows which account to build transactions for. - **Header Name:** `x-hedera-account-id` -- **Value:** Your Hedera Testnet Account ID (e.g., `0.0.12345`) +- **Value:** Your [Hedera Testnet Account ID](https://portal.hedera.com/dashboard) (e.g., `0.0.12345`) On the initialize request, the server queries the Hedera Mirror Node to fetch the associated public key and configures the agent's scope for your account. If the account cannot be found on the Mirror Node, the initialize request returns `400` with an explanatory error. @@ -58,7 +58,7 @@ Most MCP-compatible clients accept a JSON configuration block. Register the host } ``` -Replace `0.0.YOUR_ACCOUNT_ID` with your Hedera Testnet account ID. After updating the configuration, restart your client — the Hedera tools should appear in its tool list. +Replace `0.0.YOUR_ACCOUNT_ID` with your [Hedera Testnet account ID](https://portal.hedera.com/dashboard). After updating the configuration, restart your client — the Hedera tools should appear in its tool list. > [!WARNING] > **Read-Only / Query Only for Standard IDEs & GUI Clients:** General-purpose AI clients like **Cursor** and **Claude Desktop** have no built-in capability to sign or submit raw transaction bytes returned by the Hosted MCP Server. @@ -73,13 +73,15 @@ Replace `0.0.YOUR_ACCOUNT_ID` with your Hedera Testnet account ID. After updatin ## Working with RETURN_BYTES -Because the hosted server never signs transactions, every state-changing tool returns a response containing the unsigned, hex-encoded transaction bytes. To complete an operation, your client must: +Because this server never handles your private keys or signs transactions on your behalf, any action that changes data on the blockchain will come back to you as transaction data (bytes) to be signed and submitted on-chain. + +To use this MCP server, you must build or use a client application for this MCP that can: 1. Receive the hex bytes from the tool response. 2. Decode and sign them using a Hedera SDK with the account's private key. 3. Submit the signed transaction to the Hedera network. -Read-only queries — balances, token info, transaction records, exchange rates, and similar — return their results directly. No signing is required for those. +Read-only queries such as balances, token info, transaction records, exchange rates, and similar can return their results directly through your AI application, since no transaction signature is required. See the [Hedera Agent Kit examples](https://github.com/hashgraph/hedera-agent-kit-js/blob/main/examples/langchain-v1/return-bytes-tool-calling-agent.ts) for examples of signing and submitting transaction bytes.