Hyblock Capital MCP Server

An MCP server exposing the full Hyblock Capital API as tools for AI assistants (Claude, Gemini, etc.).

Transport: HTTP (MCP over stdio → upstream calls via HTTPS to Hyblock API)

Features

• ✅ 53 tools covering all Hyblock API endpoints
• ✅ OAuth2 token caching — automatically refreshes tokens before expiry
• ✅ Typed parameters with descriptions for every tool
• ✅ Clear error messages including HTTP status codes from the API

Tool Categories

Prerequisites

1. A Hyblock Capital account with API access
2. Your client_id, client_secret, and x-api-key from the API Explorer
3. Node.js ≥ 18

Setup

git clone <repo-url>
cd mcp
npm install
npm run build

Configuration

Set these environment variables before running (locally or in Railway):

export HYBLOCK_CLIENT_ID="your_client_id"
export HYBLOCK_CLIENT_SECRET="your_client_secret"
export HYBLOCK_API_KEY="your_api_key"

Add the server to your MCP client configuration (e.g., claude_desktop_config.json).

Option 1: Local Deployment (Standard)

Use this if you are running the server on your own machine.

{
  "mcpServers": {
    "hyblock-local": {
      "command": "node",
      "args": ["mcp/dist/index.js"],
      "env": {
        "HYBLOCK_CLIENT_ID": "your_client_id",
        "HYBLOCK_CLIENT_SECRET": "your_client_secret",
        "HYBLOCK_API_KEY": "your_api_key"
      }
    }
  }
}

Option 2: Deployed Deployment (Railway / Cloud)

Use this if you have deployed the server to Railway. This uses the SSE (Server-Sent Events) over HTTP transport.

#### Setup in Railway

1. Connect your GitHub repository to Railway.
2. Add the following Environment Variables (all are required; the server will refuse to start if any are missing or empty):

• HYBLOCK_CLIENT_ID
• HYBLOCK_CLIENT_SECRET
• HYBLOCK_API_KEY

1. Railway will use the Dockerfile to build and deploy. It will automatically assign a PORT.

#### How to "Enter" in MCP Clients Once live, your server will have a base URL (e.g., https://hyblock-mcp-production.up.railway.app).

For most MCP clients (like Claude Desktop), you must point them to the /sse endpoint, not the bare root:

{
  "mcpServers": {
    "hyblock-remote": {
      "url": "https://your-railway-app.up.railway.app/sse"
    }
  }
}

Note: If your client doesn't support the `url` field yet, you can use a small node bridge or the local version.

If you see ❌ API Error (401) or ❌ API Error (403) from any Hyblock tools, first verify that:

• HYBLOCK_CLIENT_ID, HYBLOCK_CLIENT_SECRET, and HYBLOCK_API_KEY are correctly set in the server environment (Railway or local).
• Your MCP client configuration is using the /sse endpoint as shown above.

Authentication Flow

The server implements the OAuth2 Client Credentials flow automatically:

1. On first API call, it exchanges client_id:client_secret (Base64 encoded) for a Bearer token via POST /oauth2/token
2. The token is cached in memory until 60 seconds before expiry
3. Subsequent calls reuse the cached token — no manual refresh needed

Tools Categorization

The server exposes 53 tools across these areas:

• System: Health check, Catalog (use this to find valid coins/exchanges).
• Orderflow: 19 tools (CVD, Bot Tracker, Slippage, etc).
• Funding: Perpetual funding rates.
• Liquidity: Liquidation heatmaps and levels.
• Sentiment: Whale/Retail delta and market sentiment indexes.
• And more...

Common Parameters

Most tools accept these optional parameters:

Tip: Call hyblock_catalog first to discover valid coin and exchange values.