README - Hedera MCP Server by mateuszm-arianelabs

Hedera MCP Server

This project provides a server that integrates with a Langchain wrapper to interact with the Hedera network. It allows users to perform Hedera operations through natural language commands facilitated by the Langchain setup.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (20 or later recommended)
pnpm (npm install -g pnpm)
Git

Quickstart

The whole thing consists of two services that we need to run.

Clone the repository:

git clone https://github.com/mateuszm-arianelabs/hedera-mcp-server.git
cd hedera-mcp-server

Set up environment variables in packages:
- You need to copy the .env.example file and create .env from it in two locations:
  - packages/langchain-proxy
  - packages/mcp-server

Edit the .env file and fill in the required configuration values (e.g., Hedera keys, network details).

API_URL=                  # url to langchain proxy endpoint
PORT=                     # port on which MCP server will be started
MCP_AUTH_TOKEN=           # array of accepted tokens separated by comas
LANGCHAIN_PROXY_TOKEN=    # token for accessing the Langchain proxy

Install dependencies:
```
pnpm install
```
Start Lang chain Proxy Service
```
pnpm run dev:lc
```
(Or pnpm start for production mode, if configured).
Run the mcp server:
```
pnpm run dev:mcp
```
(Or pnpm start for production mode, if configured).

Available Tools

Interact with Hedera: This core functionality enables the server to make calls to the running Langchain wrapper service. The wrapper then interprets these requests and performs the corresponding actions on the Hedera network (e.g., creating tokens, transferring HBAR, interacting with smart contracts).

Configuration for Visual Studio Code

To establish a connection with an MCP server, the X-MCP-AUTH-TOKEN header is required.

Below is an example .vscode/settings.json configuration for Visual Studio Code:

{
    "mcp": {
        "inputs": [],
        "servers": {
            "hedera": {
                "type": "sse",
                "url": "http://localhost:3000/sse",
                "headers": { "X-MCP-AUTH-TOKEN": "your-mcp-auth-token"}
            }
        }
    }
}

Note: Currently, passing additional headers (such as X-MCP-AUTH-TOKEN) is not supported in Cursor IDE. Source: Cursor Forum However, MCP integration is evolving rapidly, and support for custom headers is expected to be added in future versions of Cursor and other MCP Client Tools.

Potential Transition to OAuth

As of March 2025, the official MCP OAuth specification has been published, but it still has several limitations and implementation challenges. A revision of the approach is likely (source).

In preparation for future OAuth integration, here are some example repositories that showcase MCP + OAuth setups:

These can be used as references when considering OAuth-based authentication for MCP servers in future development phases.

Simplified Architecture

Architecture Diagram

API Documentation (langchain-proxy)

GET /sse

Establishes a Server-Sent Events (SSE) connection with the MCP server.

Request

GET /sse
X-MCP-AUTH-TOKEN: example-token

Header	Type	Description
X-MCP-AUTH-TOKEN	string	Required authentication token that must match one of the tokens in servers env file (MCP_AUTH_TOKEN variable)

Response

On successful authentication, establishes an SSE connection with content type text/event-stream.

Status Codes

200 OK: Connection established successfully 401 Unauthorized: Invalid or missing authentication token

Error response

{
      "content": [
        {
          "type": "text",
          "content": "Unauthorized: Invalid or missing X-MCP-AUTH-TOKEN header"
        }
      ]
    }