Hotstuff MCP

MCP server for Hotstuff Labs built on the published @hotstuff-labs/ts-sdk npm package.

Quick Start From NPM

Most users should run this package through their MCP client with npx. No repo clone or build step is needed.

Cursor or Claude Desktop

Create .cursor/mcp.json in your project, or add the same server through your client MCP settings:

{
  "mcpServers": {
    "hotstuff": {
      "command": "npx",
      "args": ["-y", "@yash-dynamo/mcp11"],
      "env": {
        "HOTSTUFF_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Then ask your assistant things like:

Search Hotstuff markets
Get portfolio for 0xYourAccountAddress
Show the BTC-PERP orderbook
Suggest a long BTC-PERP trade for $100 notional with 3x leverage

Account tools accept an accountAddress from the prompt. You can also set a default account in mcp.json:

{
  "mcpServers": {
    "hotstuff": {
      "command": "npx",
      "args": ["-y", "@yash-dynamo/mcp11"],
      "env": {
        "HOTSTUFF_MCP_TRANSPORT": "stdio",
        "HOTSTUFF_ACCOUNT_ADDRESS": "0xYourAccountAddress"
      }
    }
  }
}

Trading tools need a registered Hotstuff agent key:

{
  "mcpServers": {
    "hotstuff": {
      "command": "npx",
      "args": ["-y", "@yash-dynamo/mcp11"],
      "env": {
        "HOTSTUFF_MCP_TRANSPORT": "stdio",
        "HOTSTUFF_ACCOUNT_ADDRESS": "0xYourAccountAddress",
        "HOTSTUFF_AGENT_PRIVATE_KEY": "0xyour64byteagentkey"
      }
    }
  }
}

Claude Code Remote HTTP

If you run this server as a hosted HTTP MCP endpoint, connect Claude Code with:

claude mcp add --transport http hotstuff https://your-domain.example/mcp

With bearer auth:

claude mcp add --transport http hotstuff https://your-domain.example/mcp \
  --header "Authorization: Bearer your-token"

Claude Code uses the MCP tools over HTTP. ChatGPT Apps-compatible hosts can render the iframe widgets; Claude Code itself does not render the ChatGPT widget UI.

ChatGPT Apps / Custom Connector

Run the server over HTTPS and paste the /mcp URL into ChatGPT connector setup:

https://your-domain.example/mcp

For local tunnel testing, expose port 3100 with ngrok and use:

https://your-ngrok-domain.ngrok-free.dev/mcp

Run the server with the tunnel origin so widget metadata uses the same public domain:

HOTSTUFF_WIDGET_BASE_URL=https://your-ngrok-domain.ngrok-free.dev \
npx -y @yash-dynamo/mcp11

The widget domain is the origin only, for example https://your-ngrok-domain.ngrok-free.dev. Do not include /mcp or /sse in HOTSTUFF_WIDGET_BASE_URL.

Local HTTP Server

Install and run from npm:

npx -y @yash-dynamo/mcp11

Or from a cloned repo:

npm install
npm run build
npm run start

The server listens on port 3100 by default and exposes:

http://localhost:3100/mcp
http://localhost:3100/health
http://localhost:3100/widgets/metadata.json

Set HOTSTUFF_MCP_AUTH_TOKEN to require Authorization: Bearer <token> on /mcp, /sse, and /messages. If omitted, local requests are accepted without auth.

Use It

• Ask for market data with tools like search_markets, analyze_market, or show_orderbook
• Use account tools like get_portfolio, show_portfolio_chart, and view_open_orders
• Use suggest_trade to render a trade action card; clicking the card action calls execute_order
• If HOTSTUFF_AGENT_PRIVATE_KEY is set, trading tools sign as the agent wallet and do not need the main account private key
• HOTSTUFF_PRIVATE_KEY is accepted as a compatibility alias for HOTSTUFF_AGENT_PRIVATE_KEY

What it does

• Uses the official Hotstuff TypeScript SDK for transport, request formatting, and EIP-712 signing
• Exposes rich ChatGPT Apps HTML components for portfolio, credentials, and trade signals
• Separates read-only tools from signed tools so public queries work without a private key
• Registers MCP resources (protocol metadata, live snapshots) for assistants to read without tool calls
• Exposes MCP prompts and resource templates for guided workflows
• Ships server instructions so models treat writes as confirm-first
• Fully standalone — no sibling repositories or local file dependencies required

Environment

Public market tools work without authentication. This server is mainnet-only.

| Variable | Purpose | |----------|---------| | HOTSTUFF_MCP_AUTH_TOKEN | Optional bearer token required by the HTTP MCP endpoints. | | HOTSTUFF_MCP_PORT | Optional HTTP server port. Defaults to 3100. | | HOTSTUFF_WIDGET_BASE_URL | Public widget origin/domain, usually your HTTPS tunnel or ingress origin. Example: https://mcp.kubernetesdive.com, not /mcp or /sse. Defaults to local HTTP on the MCP port. | | HOTSTUFF_WIDGET_DOMAIN | Explicit alias for HOTSTUFF_WIDGET_BASE_URL. Accepts either an origin or a full endpoint URL and normalizes to the origin. | | HOTSTUFF_MCP_PUBLIC_URL | Compatibility alias for HOTSTUFF_WIDGET_BASE_URL. | | HOTSTUFF_ACCOUNT_ADDRESS | Default account for account-scoped reads when user is omitted. | | HOTSTUFF_AGENT_PRIVATE_KEY | Preferred signer for trading tools such as execute_order, cancel_*, and balance moves. The main account private key is not needed for normal agent trading. This key is not used to derive the owner account address. | | HOTSTUFF_PRIVATE_KEY | Compatibility alias for HOTSTUFF_AGENT_PRIVATE_KEY. | | HOTSTUFF_ACCOUNT_PRIVATE_KEY | Optional owner key. Not required for the compact trading tool surface. | | HOTSTUFF_HTTP_TIMEOUT_MS | HTTP transport timeout in ms (default: 3000). | | HOTSTUFF_MAINNET_API_URL | Optional override for mainnet API base URL. | | HOTSTUFF_MAINNET_RPC_URL | Optional override for mainnet RPC base URL. | | HOTSTUFF_MAINNET_WS_URL | Optional override for mainnet WebSocket base URL. |

This server is hard-wired to Hotstuff mainnet endpoint defaults or explicit mainnet overrides.

Install and run

Build uses esbuild to bundle this project with the Hotstuff SDK so node can run a single dist/index.js (the SDK’s published ESM entry is not directly executable as a child process in many Node versions).

Develop: npm run dev builds once, watches source changes, and starts dist/index.js with Node watch mode. Use npm run dev:build only when you want the esbuild watcher without the server.

The process starts an HTTP MCP server and logs the local /mcp URL when it is ready, plus the legacy /sse URL for compatibility. You can preview the widgets directly in a browser at http://localhost:3100/widgets/portfolio.html, http://localhost:3100/widgets/trade-signal.html, and http://localhost:3100/widgets/credentials.html.

MCP resources

| URI | Description | |-----|-------------| | ui://widget/credentials.html | ChatGPT Apps UI credential prompt for account address and trading signer key. | | ui://widget/portfolio.html | ChatGPT Apps UI portfolio widget template. | | ui://widget/trade-signal.html | ChatGPT Apps UI trade signal / action widget template. | | hotstuff://exchange-opcodes | JSON map of exchange action names to op codes. | | hotstuff://endpoints | Default API/RPC/WS bases for the active network. | | hotstuff://instruments | Live instruments({ type: "all" }) snapshot with fetchedAt. | | hotstuff://supported-collateral | Live supported collateral snapshot with fetchedAt. |

Resource templates:

• hotstuff://instrument/{symbol} - live per-instrument snapshot with ticker and orderbook
• hotstuff://block/{block_height} - live block snapshot by height

Tool reference

Market

• analyze_market
• analyze_markets_batch
• search_markets
• show_market_overview
• show_chart
• show_orderbook
• market_picks

Portfolio

• get_portfolio
• show_portfolio_chart
• view_open_orders

Trading

• suggest_trade
• execute_order
• close_position
• close_positions_batch
• modify_position
• update_leverage
• cancel_order

Help

• help

Apps-enabled tools return structuredContent and point ChatGPT to HTML components with _meta.ui.resourceUri plus the ChatGPT compatibility alias _meta["openai/outputTemplate"]. get_portfolio, show_portfolio_chart, suggest_trade, and market_picks mount the portfolio or trade signal widget directly. The trade signal widget calls execute_order only from its explicit execute button and uses the confirmPayload returned by suggest_trade.

If an account or trading signer is missing, account and trading tools return a credential_request widget instead of failing. The credentials widget asks for only the missing fields, then retries the original target tool with per-call credentials. Private keys supplied this way are used for that tool call and are redacted from logs.

execute_order uses the same Hotstuff SDK placeOrder payload shape and fills SDK-required defaults for triggerPx, isMarket, tpsl, and grouping when they are omitted in the MCP call.
Signed write helpers use millisecond Unix timestamps for expiry defaults, matching the SDK's Date.now() + ... style expiresAfter and validUntil values.
execute_order uses HOTSTUFF_AGENT_PRIVATE_KEY for normal agent trading, so the main account private key is not needed once the agent exists.