Hive Intelligence home
Hive Intelligence
GitHub

Get Started

Quick Start Guide

Written by , Product docsLast updated

Connect Hive to one supported AI client, verify a live tool call, then choose the integration path that matches your stack. MCP is the native surface for agents, REST is the backend execution path, category MCP narrows discovery for focused agents, and the CLI is best for local scripts and setup checks.

View MarkdownAsk ClaudeAsk ChatGPT

For the shortest setup flow, start with Get Started: key -> client setup -> live tool call -> discovery -> production surface. This page gives the detailed examples behind that flow.

1. Connect Hive's remote MCP server

Create or select a Hive API key at /dashboard/keys, then connect the remote MCP server from your AI client.

ItemValue
Remote MCP URLhttps://mcp.hiveintelligence.xyz/mcp
TransportStreamable HTTP
Auth headerAuthorization: Bearer YOUR_HIVE_API_KEY
Client setupClaude Desktop, Claude Code, Cursor, OpenAI Responses API, Codex CLI, Gemini CLI, Windsurf, VS Code

2. Verify one live tool call

After setup, start a fresh client session and ask:

"Use Hive tools to get the current price of Bitcoin and Ethereum in USD."

The first successful response should show a Hive tool call and live provider-backed price data. Use that result to confirm the client discovers a tool, calls Hive, and answers from current crypto data instead of training memory.

3. Run a REST smoke test

Use REST when your backend, bot, cron job, or serverless function owns execution, or when you want a client-independent key and payload check.

bash
curl -X POST https://mcp.hiveintelligence.xyz/api/v1/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY" \
  -d '{
    "tool": "get_price",
    "args": {
      "ids": "bitcoin,ethereum",
      "vs_currencies": "usd"
    }
  }'

The current REST payload keys are tool and args.

Expected response shape

You should receive JSON with ok, data, and meta. The provider payload can vary by tool, but the first response should include both live price data and Hive execution metadata. The values below are an illustrative response shape, not current market data:

json
{
  "ok": true,
  "data": {
    "bitcoin": {
      "usd": 67234
    },
    "ethereum": {
      "usd": 3521.5
    },
    "_hive": {
      "provider": "CoinGecko",
      "tool": "get_price",
      "runtime_status": "ok",
      "fetched_at": "2026-05-30T14:23:18.000Z"
    }
  },
  "meta": {
    "tool": "get_price",
    "provider": "CoinGecko",
    "runtime_status": "ok",
    "fetched_at": "2026-05-30T14:23:18.000Z"
  }
}

The important checks are ok: true, current provider data under data, and metadata such as provider, runtime_status, and fetched_at.

Common first-call failures

  • 403 Invalid API key (INVALID_API_KEY) - double-check the key, confirm you are using Authorization: Bearer YOUR_KEY, and look for trailing whitespace or newline characters. A missing key returns 401 AUTH_REQUIRED.
  • 429 Rate limit - wait for the Retry-After: 60 window, check usage in the dashboard, or move to a plan with higher limits.
  • 404 Invalid tool name (TOOL_NOT_FOUND) - tool names are snake_case. Use tools/list, hive://tools, or GET /api/v1/tools to get the current authoritative list.
  • Client does not see tools - restart the MCP client after editing config; category endpoints only expose tools in that category.

See the full error reference and rate limits docs for retries, backoff, and error codes.

4. Choose your integration path

  • REST API - use it when your backend, bot, cron job, or serverless function owns execution. Continue with API Integration.
  • Root MCP - use it when Claude, Cursor, OpenAI Responses API, Codex CLI, Gemini CLI, or another MCP client that supports Streamable HTTP and API-key headers should discover Hive tools. Start with Install in your AI client.
  • Category MCP - use it when you want a smaller direct tool list for one domain such as market data or security. Pick an endpoint from Tools Reference.
  • CLI - use it when you want terminal setup, catalog checks, scripted calls, or daily briefings. Read the CLI Reference.

Decision point: by this point you should know whether the caller is an MCP client, a backend over REST, a terminal workflow, or a focused category agent. If that is still ambiguous, start with root MCP for agents and REST for applications.

Reference examples

Root MCP endpoint

Use the root endpoint when your client supports MCP and you want access to the full discovery flow.

Endpoint: POST https://mcp.hiveintelligence.xyz/mcp

Useful root discovery surfaces:

  • tools/list for the compact discovery layer
  • hive://tools for the full live tool inventory
  • hive://toolsets, hive://skills, and hive://status for task routing, agent skill metadata, and runtime status semantics
  • get_api_endpoint_schema for parameter lookup

Example MCP call:

json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "invoke_api_endpoint",
    "arguments": {
      "endpoint_name": "get_price",
      "args": {
        "ids": "bitcoin",
        "vs_currencies": "usd"
      }
    }
  },
  "id": 1
}

Category-scoped MCP endpoint

Use a category endpoint when you want a smaller direct tool surface.

Example:

bash
curl -X POST https://mcp.hiveintelligence.xyz/hive_market_data/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

CLI

The safest CLI workflow is direct tool execution against the live catalog.

bash
npx -y -p hive-intelligence@latest hive tools list
npx -y -p hive-intelligence@latest hive tools info get_price
npx -y -p hive-intelligence@latest hive tools call get_price --args '{"ids":"bitcoin","vs_currencies":"usd"}'

The npm package is hive-intelligence; the executable is hive. Install globally with npm i -g hive-intelligence to drop the npx prefix.

Verify tool discovery

bash
curl -X GET "https://mcp.hiveintelligence.xyz/api/v1/tools?search=price&limit=5" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY"

If you need the full wrapped catalog, see Live Catalog.

Run an end-to-end query

Once your connection works, run one of these end-to-end examples:

  • Price check: call get_price with {"ids":"bitcoin,ethereum","vs_currencies":"usd"} and confirm you get a live response from CoinGecko.
  • Security scan: call get_token_security with {"chainId":"1","contract_addresses":"0x6982508145454Ce325dDbE47a25d4ec3d2311933"} and inspect the PEPE risk flags.
  • DeFi overview: call get_defi_protocols with {"limit":10,"offset":0} and look at the top TVL protocols.
  • Wallet portfolio: call alchemy_get_token_balances_by_wallet with {"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","network":"eth-mainnet"} and you should see a token breakdown for vitalik.eth.

These exercise four different provider backends through the same request shape, which confirms Hive's normalized execution contract.

Production checklist

  1. Keep your API key safe. Every call to mcp.hiveintelligence.xyz should use Authorization: Bearer YOUR_HIVE_API_KEY; x-api-key is accepted as a legacy alias.
  2. Verify the official MCP endpoint before approving a client connection: https://mcp.hiveintelligence.xyz/mcp. Do not approve a look-alike MCP URL or marketplace entry that points somewhere else.
  3. Store keys in environment variables or your secret manager. Do not commit keys to mcp.json, scripts, or app source.
  4. Verify tool discovery before hard-coding tool names. Use MCP tools/list, hive://tools, REST GET /api/v1/tools, or the live catalog.
  5. Use client tool-call approval or review prompts where supported, and read MCP Security before enabling stateful tools or downstream actions based on Hive results.

Next steps

Previous
Client Setup
Next
Playground