Hedera Docs MCP Server Setup Guide

Connect your AI tools to the official Hedera documentation for real-time, accurate answers to your Hedera-related questions directly from the source.

What Is the Hedera MCP Server?

The Model Context Protocol (MCP) is an open standard that creates direct connections between AI applications and external data sources. Instead of relying on general web search results, MCP lets AI tools search your documentation directly for more accurate, up-to-date information. Hedera’s MCP server gives any MCP-compatible AI application access to every page in the Hedera docs navigation, including:

API references and SDK documentation
Code examples and tutorials
How-to guides and quickstarts
Network concepts and architecture docs
The OpenAPI specs for the mirror node REST API, the smart contract verification API, and the Hedera status API

Available Tools

The server exposes three tools:

Tool	What it does	Read-only
`search_hedera`	Searches the documentation and returns matching snippets with page titles and links. Use it for broad or conceptual questions.	Yes
`query_docs_filesystem_hedera`	Runs read-only shell-style commands (`rg`, `grep`, `find`, `tree`, `ls`, `cat`, `head`, `jq`, and more) against a sandboxed, in-memory copy of the docs pages and the OpenAPI specs. Use it to read a full page, read several pages in one call, run exact keyword or regex searches, or explore the docs structure.	Yes
`submit_feedback`	Sends a report about an incorrect, outdated, confusing, or incomplete page to the Hedera docs team. Takes the page path and a description of the problem.	No

The filesystem tool is how an AI tool reads a complete page. Every page at the URL path /some/page is available at /some/page.mdx, and the OpenAPI specs are mounted under /openapi/ (openapi.yaml, hedera-status-api.yaml, and smart-contract-verification-api.yaml). The specs are stored as single-line JSON despite the .yaml name, so query them with jq rather than head. For example, an agent can call it with:

head -200 /learn/getting-started/mcp-setup.mdx
rg -il "MirrorNodeTokenBalanceQuery" /native
jq -r '.info.title, (.paths | keys[])' /openapi/openapi.yaml

Each filesystem call is stateless: the working directory resets to / and nothing carries over between calls. Output is truncated to 30 KB per call. search_hedera and query_docs_filesystem_hedera only read published documentation. Both carry the MCP annotations readOnlyHint: true and destructiveHint: false, which some AI tools use to run them without asking for approval. submit_feedback is the one tool that sends data: when an AI tool calls it, the page path and feedback text are recorded as page feedback in the Hedera docs team’s Mintlify analytics dashboard. The server also publishes a hedera skill as an MCP resource. MCP gives an agent access to the docs content, and the skill tells it how to use that content, so connecting the server gives agents both. Search and the filesystem cover the pages in the docs navigation. Pages hidden from the navigation are not included.

Tool names are specific to each Mintlify-hosted server. Use the names your AI tool reports from the server rather than hardcoding them.

MCP Server URL

https://docs.hedera.com/mcp

Use this URL to connect any supported AI tool to the Hedera documentation.

Why MCP Over Web Search?

Feature	Web Search	MCP
Source	Search engine index (may be stale or incomplete)	The current indexed Hedera docs, searched directly
Noise	Affected by SEO and ranking algorithms	Goes straight to official docs
Integration	Separate step from response generation	Searches during response generation
Accuracy	May surface outdated or third-party content	Answers come from the official docs rather than training data or third-party pages

Installation

The Hedera MCP server is a remote HTTP server hosted by Mintlify. No code is downloaded or executed on your machine. Your AI tool connects directly to https://docs.hedera.com/mcp over HTTPS and reads the documentation through the tools listed above. The server requires no authentication, wallet, or keys. To connect, you manually add the server URL to your AI tool’s configuration using the setup instructions below. This is the recommended approach because it gives you full visibility into what’s being configured, and no third-party packages are installed or executed on your system.

Quick Connect From Any Docs Page

The contextual menu at the top of every page on docs.hedera.com includes these options:

Option	What it does
Copy MCP server URL	Copies `https://docs.hedera.com/mcp` to your clipboard.
Connect to Cursor	Installs the Hedera MCP server in Cursor.
Connect to VS Code	Installs the Hedera MCP server in VS Code.

Setup by Tool

Note

If you run into issues, refer to the Additional Resources section below as setup instructions can change and that’s where you’ll find the most current guidance.

Claude (Web & Mobile)

Claude supports MCP servers as custom connectors. Available on free, Pro, Max, Team, and Enterprise plans (free users are limited to one custom connector). Steps:

Navigate to Customize → Connectors (or go directly to claude.ai/settings/connectors).
Click the ”+” button next to Connectors, then select “Add custom connector”.
Enter the details:
- Name: Hedera Docs
- URL: https://docs.hedera.com/mcp
Click Add.
In any chat, click the ”+” button in the lower left of the chat interface, then hover over “Connectors” to enable Hedera Docs for that conversation.

Claude will automatically use the Hedera Docs tools when your questions relate to Hedera development.

Claude Desktop

Claude Desktop supports remote MCP servers through custom connectors and local servers through Desktop Extensions. For remote servers (like Hedera’s):

Click the ”+” button at the bottom of the chat box, then select “Connectors”.
If you haven’t added the Hedera connector yet, navigate to Settings → Developer → Connectors and click “Add custom connector”.
Enter the details:
- Name: Hedera Docs
- URL: https://docs.hedera.com/mcp
Click Add and restart Claude Desktop if prompted.

Note: Custom connectors added on Claude web (claude.ai) are also available in Claude Desktop and Claude mobile when signed in with the same account.

Claude Code

Claude Code connects to MCP servers via CLI commands. Steps: Run the following command in your terminal:

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

Verify the connection:

claude mcp list

You should see hedera-docs listed as a connected server.

Cursor IDE

Cursor supports MCP servers through its mcp.json configuration file. Option A: Command Palette (Recommended)

Press Cmd + Shift + P (macOS) or Ctrl + Shift + P (Windows/Linux).
Search for “Open MCP settings”.
Select Add custom MCP.
Add the following to mcp.json:

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

Option B: Manual Configuration Create or edit the mcp.json file at one of these locations:

Scope	Path
Global (all projects)	`~/.cursor/mcp.json`
Project-specific	`.cursor/mcp.json` (in project root)

Verify the connection: In Cursor’s chat, ask “What tools do you have available?” and confirm the Hedera Docs server appears.

VS Code (GitHub Copilot)

VS Code supports MCP servers via the .vscode/mcp.json file, available when using GitHub Copilot in Agent mode. Steps:

Create the file .vscode/mcp.json in your project root.
Add the following configuration:

{
  "servers": {
    "hedera-docs": {
      "type": "http",
      "url": "https://docs.hedera.com/mcp"
    }
  }
}

In the Copilot chat panel, switch to Agent mode and restart the MCP server if prompted.

Note: VS Code uses a "servers" key (not "mcpServers") and requires a "type" field.

Devin Desktop

Devin Desktop, formerly Windsurf, connects to MCP servers through its Devin Local agent. Devin Local supports the stdio, Streamable HTTP, and SSE transport types.

Open or create the MCP config file for the scope you want:
- User (all your projects): ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows)
- Project (shared through version control): .devin/mcp_config.json
Add the following:

{
  "mcpServers": {
    "hedera-docs": {
      "url": "https://docs.hedera.com/mcp",
      "transport": "http"
    }
  }
}

In the Agents window, click Customize in the agent sidebar, then click MCPs. hedera-docs appears in the This computer list. Refresh the list if it doesn’t.

If you also use Devin CLI, this command adds the server to the same user config file:

devin mcp add -s user hedera-docs https://docs.hedera.com/mcp

Note: The Available list on the MCPs tab shows servers from your MCP registries. Add the Hedera docs server through the config file rather than installing a similarly named third-party server from that list.

ChatGPT

ChatGPT connects to remote MCP servers through plugins. Account and workspace policies apply to adding and using custom MCP servers; on Enterprise workspaces, an admin controls these permissions. Steps (ChatGPT web):

Go to ChatGPT Plugins.
Select the ”+” button, then Add custom MCP server.
Enter the details:
- Name: Hedera Docs
- Description: Search the official Hedera documentation.
Under Connection, enter the URL https://docs.hedera.com/mcp.
The Hedera docs server is public and needs no authentication. Review the risk warning and select I understand and want to continue.
Select Create as a plugin, then review the discovered tools. You should see search_hedera, query_docs_filesystem_hedera, and submit_feedback.
Install the plugin, start a new conversation, type @ in the prompt box, and select Hedera Docs.

ChatGPT desktop app: open Settings → MCP servers, select Add server, enter Hedera Docs as the name, choose Streamable HTTP, and enter https://docs.hedera.com/mcp. Save the server, then select Restart.

Note: ChatGPT deep research and company knowledge expect an MCP server with tools named exactly search and fetch. The Hedera docs server uses different tool names, so use it in regular conversations through the plugin. See Connect and test your plugin for OpenAI’s current instructions.

Codex

Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share MCP configuration in ~/.codex/config.toml. You can also scope the server to one project with .codex/config.toml, which Codex only reads for trusted projects. Steps:

Add the Hedera MCP server to ~/.codex/config.toml:

[mcp_servers.hedera-docs]
url = "https://docs.hedera.com/mcp"

Start a Codex session and ask “What tools do you have available?” Codex should list the Hedera Docs tools.

Gemini CLI

Google’s Gemini CLI supports MCP servers through a settings.json configuration file. It supports stdio, SSE, and Streamable HTTP transports. Steps:

Open or create the Gemini CLI settings file:

~/.gemini/settings.json

Add the Hedera MCP server:

{
  "mcpServers": {
    "hedera-docs": {
      "url": "https://docs.hedera.com/mcp",
      "type": "http"
    }
  }
}

Or add it from the command line, which writes the same entry:

gemini mcp add --scope user --transport http hedera-docs https://docs.hedera.com/mcp

"type": "http" selects the Streamable HTTP transport, which the Hedera docs server uses; it does not accept SSE connections. These settings need Gemini CLI v0.21.0 or later. Earlier versions treat url as an SSE endpoint and cannot connect, so use "httpUrl": "https://docs.hedera.com/mcp" instead (current versions still accept httpUrl but mark it deprecated).

Launch Gemini CLI and verify with:

/mcp

You should see the hedera-docs server listed with its available tools.

Prerequisite: Install Gemini CLI with npm install -g @google/gemini-cli@latest.

Using Multiple MCP Servers

You can connect the Hedera MCP server alongside other documentation MCP servers. Here’s an example Cursor configuration with multiple servers:

{
  "mcpServers": {
    "hedera-docs": {
      "url": "https://docs.hedera.com/mcp"
    },
    "another-docs": {
      "url": "https://example.com/docs/mcp"
    }
  }
}

Connected MCP servers do not add documentation content to the conversation until the AI calls a tool. The AI decides when to search based on query relevance, so it doesn’t search every connected server for every question. When it does search, each query returns multiple results, so searching several servers for one question can make the conversation much longer and leave less room for the response. Best practices for multiple servers:

Connect only the servers relevant to your current work.
Be specific in your prompts so the AI searches the most relevant server.
Disconnect servers you’re not actively using to reduce context usage.

Configuration Reference

A quick-reference table of config file paths and JSON formats for each tool:

Tool	Config File Path	Server Key	URL Key
Cursor (global)	`~/.cursor/mcp.json`	`mcpServers`	`url`
Cursor (project)	`.cursor/mcp.json`	`mcpServers`	`url`
VS Code	`.vscode/mcp.json`	`servers`	`url` (+ `type: "http"`)
Devin Desktop (user)	`~/.config/devin/mcp_config.json`	`mcpServers`	`url` (+ `transport: "http"`)
Devin Desktop (project)	`.devin/mcp_config.json`	`mcpServers`	`url` (+ `transport: "http"`)
Claude (Web)	Customize → Connectors	UI-based	URL field
Claude Desktop	Settings → Developer → Connectors	UI-based	URL field
Claude Code	CLI: `claude mcp add`	—	—
Codex	`~/.codex/config.toml`	`mcp_servers.<name>`	`url`
Gemini CLI	`~/.gemini/settings.json`	`mcpServers`	`url` (+ `type: "http"`)
ChatGPT (web)	chatgpt.com/plugins → + → Add custom MCP server	UI-based	URL field
ChatGPT (desktop)	Settings → MCP servers → Add server	UI-based	URL field

Troubleshooting

Server not connecting?

Verify the URL is exactly https://docs.hedera.com/mcp (no trailing slash).
Ensure you have an active internet connection.
Restart your AI tool after adding the configuration.

Tools not appearing?

The server exposes three tools: search_hedera, query_docs_filesystem_hedera, and submit_feedback. If none appear, the connection failed.
In Cursor/VS Code, click the refresh button next to the server entry.
In Claude Code, run claude mcp list to verify the server is registered.
In Devin Desktop, open Customize → MCPs and check that hedera-docs is in the This computer list.

Search returning no results?

Try rephrasing your query with more specific Hedera terminology.
Ensure the MCP server is enabled/active for your current chat session.

Rate limits: Mintlify, which hosts the server, applies rate limits to protect availability:

Scope	Limit
Per user (IP address)	5,000 requests per hour
`search_hedera` calls across all users of docs.hedera.com	10,000 requests per hour
`query_docs_filesystem_hedera` calls across all users of docs.hedera.com	10,000 requests per hour

If a limit is exceeded, the server returns HTTP 429 Too Many Requests. Back off and retry after a short delay. Limits reset on a rolling hourly window. Mintlify sets these limits and can change them; see Mintlify’s rate limits for the current values.

Additional Resources

Writer: Krystal, Senior DX Engineer

GitHub | X

Overview

Getting Started

Core Concepts

Hedera Docs MCP Server Setup Guide

What Is the Hedera MCP Server?

Available Tools

MCP Server URL

Why MCP Over Web Search?

Installation

Quick Connect From Any Docs Page

Setup by Tool

Note

Claude (Web & Mobile)

Claude Desktop

Claude Code

Cursor IDE

VS Code (GitHub Copilot)

Devin Desktop

ChatGPT

Codex

Gemini CLI

Using Multiple MCP Servers

Configuration Reference

Troubleshooting

Additional Resources

Writer: Krystal, Senior DX Engineer

Editor: Ty, Senior Product Manager

​What Is the Hedera MCP Server?

​Available Tools

​MCP Server URL

​Why MCP Over Web Search?

​Installation

​Quick Connect From Any Docs Page

​Setup by Tool

​Note

​Claude (Web & Mobile)

​Claude Desktop

​Claude Code

​Cursor IDE

​VS Code (GitHub Copilot)

​Devin Desktop

​ChatGPT

​Codex

​Gemini CLI

​Using Multiple MCP Servers

​Configuration Reference

​Troubleshooting

​Additional Resources

Writer: Krystal, Senior DX Engineer

Editor: Ty, Senior Product Manager

What Is the Hedera MCP Server?

Available Tools

MCP Server URL

Why MCP Over Web Search?

Installation

Quick Connect From Any Docs Page

Setup by Tool

Note

Claude (Web & Mobile)

Claude Desktop

Claude Code

Cursor IDE

VS Code (GitHub Copilot)

Devin Desktop

ChatGPT

Codex

Gemini CLI

Using Multiple MCP Servers

Configuration Reference

Troubleshooting

Additional Resources