MCP Servers

Overview

Both the Python and TypeScript SDKs include built-in MCP servers. These servers give AI assistants direct access to live Hyperliquid market data — prices, liquidations, order book state, block metrics, and network health — through the standard Model Context Protocol.

The servers implement MCP protocol version 2024-11-05 over stdio transport, which means they work with any client that supports the MCP stdio specification. Once connected, an AI assistant can query real-time market data, sample streaming prices, inspect liquidation cascades, and monitor network consensus — all through natural language.

Both SDKs are open-source and available on GitHub:

Python: hypercore-sdk-mcp — installed as a CLI entry point with the Python SDK
TypeScript: hypercore-ts-mcp — runs via npx with no global install required

Claude Desktop

Python

Add the following to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aleatoric-hyperliquid": {
      "command": "hypercore-sdk-mcp",
      "env": {
        "HYPER_API_KEY": "ak_live_...",
        "HYPER_GRPC_TARGET": "hl.grpc.aleatoric.systems:443",
        "HYPER_UNIFIED_STREAM_URL": "https://unified.grpc.aleatoric.systems"
      }
    }
  }
}

TypeScript

{
  "mcpServers": {
    "aleatoric-hyperliquid": {
      "command": "npx",
      "args": ["hypercore-ts-mcp"],
      "env": {
        "HYPER_API_KEY": "ak_live_...",
        "HYPER_GRPC_TARGET": "hl.grpc.aleatoric.systems:443",
        "HYPER_UNIFIED_STREAM_URL": "https://unified.grpc.aleatoric.systems"
      }
    }
  }
}

After saving the configuration, restart Claude Desktop. The MCP server will start automatically and the 12 tools will appear in the tool picker.

Claude Code

For Claude Code (CLI), add the MCP server to your project’s .claude/settings.json:

{
  "mcpServers": {
    "aleatoric-hyperliquid": {
      "command": "hypercore-sdk-mcp",
      "env": {
        "HYPER_API_KEY": "ak_live_..."
      }
    }
  }
}

Claude Code will detect the configuration on startup and connect to the MCP server. You can then reference Hyperliquid data directly in your prompts.

Cursor

Add to Cursor’s MCP configuration via Settings > MCP Servers:

{
  "aleatoric-hyperliquid": {
    "command": "hypercore-sdk-mcp",
    "env": {
      "HYPER_API_KEY": "ak_live_..."
    }
  }
}

OpenAI (ChatGPT) / Custom Agents

For agents built with the OpenAI Agents SDK or similar frameworks that support MCP as a tool provider:

from agents import Agent
from agents.mcp import MCPServerStdio

mcp = MCPServerStdio(
    command="hypercore-sdk-mcp",
    env={
        "HYPER_API_KEY": "ak_live_...",
        "HYPER_GRPC_TARGET": "hl.grpc.aleatoric.systems:443",
    },
)

agent = Agent(
    name="market-analyst",
    instructions="You have access to live Hyperliquid market data.",
    mcp_servers=[mcp],
)

This pattern works with any agent framework that accepts MCP stdio servers as tool sources. The server process is managed by the framework — it starts when the agent initializes and stops when the session ends.

Windsurf / Continue / Other IDEs

Any IDE or tool that supports MCP stdio servers can connect using the same pattern. The command is:

Python SDK: hypercore-sdk-mcp
TypeScript SDK: npx hypercore-ts-mcp

Consult your IDE’s documentation for the exact configuration format. The environment variables and behavior are identical across all clients.

Available Tools

Once connected, the MCP server exposes 12 tools:

Tool	Description
`catalog_interfaces`	List all available API surfaces and their capabilities
`grpc_get_mid_price`	Current mid price for a specific coin (e.g., BTC, ETH)
`grpc_stream_mids_sample`	Sample N price ticks from the gRPC stream
`grpc_get_block_number`	Current HyperEVM block number
`grpc_stream_liquidations_sample`	Sample recent liquidation events from gRPC
`unified_get_stats`	Unified Stream latency summaries and hit rates
`unified_get_events`	Query filtered events by type and stream
`unified_get_liquidation_cascades`	Recent liquidation cascade signals
`unified_get_consensus_pulse`	Block height, base fees, gas delta, P2P latency
`status_get_public`	Public-facing health and status
`status_get_private`	Private diagnostics (requires elevated key)
`rpc_call`	Generic JSON-RPC call to the Hyperliquid node

The status_get_private tool requires an API key with elevated permissions. All other tools work with any valid ak_live_ key.

Environment Variables

Both MCP servers read the same configuration from environment variables:

Variable	Required	Description
`HYPER_API_KEY`	Yes	Your Aleatoric API key (`ak_live_...`)
`HYPER_GRPC_TARGET`	No	gRPC endpoint (default: `hl.grpc.aleatoric.systems:443`)
`HYPER_UNIFIED_STREAM_URL`	No	Unified Stream endpoint (default: `https://unified.grpc.aleatoric.systems`)
`HYPER_RPC_URL`	No	JSON-RPC endpoint (default: `https://rpc.aleatoric.systems/`)

In most configurations, only HYPER_API_KEY is required. The other variables default to the production Aleatoric endpoints and only need to be set if you are connecting to a different environment.

Next Steps

Python SDK — Full Python client documentation
TypeScript SDK — Full TypeScript client documentation
Unified Stream — Event types available through MCP tools
Authentication — API key management