# Hive Intelligence [![npm version](https://img.shields.io/npm/v/hive-intelligence.svg)](https://www.npmjs.com/package/hive-intelligence) [![Node.js 22.12+](https://img.shields.io/badge/node-%3E%3D22.12-339933.svg)](https://nodejs.org/) [![License: Proprietary](https://img.shields.io/badge/license-Proprietary-red.svg)](./LICENSE) [![MCP compatible](https://img.shields.io/badge/MCP-compatible-111827.svg)](https://modelcontextprotocol.io/) One connection for evidence-backed crypto due diligence. Every Hive-backed answer carries sources, freshness, and a runtime receipt. Hive gives Claude Code, Cursor, VS Code, OpenAI Responses API, Gemini CLI, Codex, and supported custom agents one compact way to discover and call live crypto data. Agents route through task toolsets, inspect schemas before execution, keep calls bounded, and return provider provenance plus runtime status instead of browsing a wall of raw endpoints. Hive is shipped as a hosted MCP server, local `stdio` runtime, CLI, and REST API. ```bash npx -y -p hive-intelligence@latest hive init --all ``` Use the hosted MCP when you want Hive to run auth, rate limits, provider infrastructure, and runtime status. Use local `stdio` when you want desktop client setup, self-hosting, or provider-key experiments. ## What You Get - Evidence-backed workflows for token diligence, wallet investigation, security checks, market research, DeFi, DEX pools, NFTs, Solana, prediction markets, and durable monitoring. - A compact eight-tool root MCP workflow surface — three direct hero tools (`get_token_price`, `check_token_safety`, `get_wallet_portfolio`) plus the five-tool discovery loop, so agents can route before they call. - Task toolsets for market research, token diligence, wallet investigation, security checks, DEX pool analysis, DeFi research, NFT research, Solana analysis, network infrastructure, prediction markets, and stateful monitoring. - CLI commands for auth, client setup, tool discovery, schema inspection, direct execution, diagnostics, aliases, polling, and config generation. - Runtime resources for providers, categories, full tool catalog, task toolsets, canaries, skills, and status metadata. - Bundled agent skills that teach assistants the right Hive workflow: discovery -> schema lookup -> bounded execution -> evidence receipt. - A broad provider catalog remains available behind discovery for agents that need a long-tail endpoint. The current catalog contains 615 tools, but that coverage is not the primary product contract. ## Quickstart Requirements: - Node.js 22.12+ (Node.js 24 LTS recommended) - npm - Browser authorization for interactive hosted MCP after OAuth activation, or a Hive API key for direct CLI, REST, and headless agents For the fastest proof before setup, run the fixed, read-only public demo. It requires no account and returns the same source/freshness/runtime-receipt shape used by authenticated calls: ```text https://www.hiveintelligence.xyz/playground ``` For direct CLI or headless REST access, create a key: ```text https://www.hiveintelligence.xyz/login?next=/dashboard/keys ``` After hosted OAuth activation, configure OAuth-capable AI clients without putting a secret in their config: ```bash npx -y -p hive-intelligence@latest hive init --all ``` For automation, exit code `0` means every detected programmable client, requested skill install, and enabled readiness check completed; partial setup returns non-zero and is detailed in `--json` output. For direct CLI or headless REST use, sign in separately: ```bash npx -y -p hive-intelligence@latest hive auth login ``` Make a first successful call: ```bash npx -y -p hive-intelligence@latest hive market price --ids bitcoin --vs usd --json ``` Expected output shape: ```json { "ok": true, "data": { "bitcoin": { "usd": 0 } }, "meta": { "provider": "CoinGecko", "runtime_status": "ok", "fetched_at": "2026-07-11T12:00:00.000Z", "observed_at": "2026-07-11T11:59:59.900Z", "cache_age_ms": 100, "source": "live", "receipt_id": "00000000-0000-4000-8000-000000000000", "receipt_version": "1.0", "server_version": "1.4.0", "build_sha": null, "digest_algorithm": "sha256", "input_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "result_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "duration_ms": 0 } } ``` Use `--json` for scripts and agents. Use `--pretty` for human-readable output. ## Connect Hosted MCP After hosted OAuth activation, use secret-free config prefill for OAuth-capable clients. Review the public URL in the client, approve it, and complete Hive authorization in the browser. These links never contain an API key: Use these native OAuth paths only after the hosted protected-resource metadata reports OAuth enabled. Until that deployment gate is open, use the API-key fallback from a trusted client/backend; do not paste a key into an install URL. [![Cursor setup](https://img.shields.io/badge/Cursor-Setup-000000.svg?logo=cursor)](https://www.hiveintelligence.xyz/install/cursor) [![VS Code setup](https://img.shields.io/badge/VS_Code-Setup-0098FF?logo=visualstudiocode&logoColor=white)](https://www.hiveintelligence.xyz/install/vs-code) The setup pages check the live OAuth and release contract before exposing a native install action, so a stale deployment cannot masquerade as a successful one-click install. Hosted MCP URL: ```text https://mcp.hiveintelligence.xyz/mcp ``` Claude Code: ```bash claude mcp add --transport http --scope user hive https://mcp.hiveintelligence.xyz/mcp ``` OpenAI Codex: ```bash codex mcp add hive --url https://mcp.hiveintelligence.xyz/mcp codex mcp login hive ``` Generic OAuth-capable Streamable HTTP config: ```json { "mcpServers": { "hive": { "url": "https://mcp.hiveintelligence.xyz/mcp" } } } ``` For headless automation that cannot open a browser, add `Authorization: Bearer $HIVE_API_KEY` from secret storage instead. ## Client Compatibility | Client | Hosted HTTP MCP | Hosted auth | Local stdio | Recommended setup | | ------------------------------------- | ---------------- | ----------------------------------- | ----------- | ---------------------------------------------------------------------------- | | Claude Code | Yes | OAuth or API-key fallback | Yes | `claude mcp add --transport http --scope user hive https://mcp.hiveintelligence.xyz/mcp` | | Cursor | Yes | OAuth or API-key fallback | Yes | Secret-free config prefill above | | VS Code | Yes | OAuth or API-key fallback | Yes | Secret-free config prefill above | | Windsurf / Devin Desktop | Yes | OAuth or API-key fallback | Yes | Add the hosted URL in MCP settings | | Gemini CLI | Yes | OAuth or API-key fallback | Yes | `gemini mcp add hive https://mcp.hiveintelligence.xyz/mcp --transport http --scope user` | | Codex | Yes | OAuth or API-key fallback | Yes | `codex mcp add hive --url https://mcp.hiveintelligence.xyz/mcp`, then `codex mcp login hive` | | OpenAI Responses API | Yes | API-key authorization token | No | Use a server-side remote MCP `tools` entry | | ChatGPT custom apps | Deployment-gated | OAuth 2.1 | No | Direct after hosted OAuth + consent activation; use Responses API until then | | Claude custom connectors/directory | Deployment-gated | OAuth 2.1 | No | Direct after hosted OAuth + consent activation | | Grok custom connectors | Deployment-gated | OAuth 2.1 | No | Add the hosted URL at `grok.com/connectors` | Header-based API key auth works today for clients or API surfaces that support custom headers or authorization tokens. The server also includes a fail-closed OAuth 2.1 foundation with PKCE, protected-resource discovery, CIMD/DCR, rotating refresh tokens, and revocation. It is disabled until the hosted deployment and the Hive consent page are configured. See [MCP OAuth 2.1 operations](docs/OAUTH.md). Codex versions that do not show `--url` in `codex mcp add --help` must be updated before the remote-MCP command will work. Run `codex update` when the installed release supports self-update; otherwise update it through the installer or package manager you originally used. Public OpenAI/Codex and Cursor plugin artifacts are staged in the public SDK, but marketplace installs are not advertised as live until external approval and clean-profile verification. See [the distribution runbook](docs/DISTRIBUTION.md). ## Run Local stdio MCP Use local `stdio` when you want a self-hosted MCP process, local desktop config, or your own upstream provider keys. ```json { "mcpServers": { "hive-local": { "command": "npx", "args": ["-y", "-p", "hive-intelligence@latest", "hive"], "env": { "COINGECKO_PRO_API_KEY": "optional", "ALCHEMY_API_KEY": "optional", "HELIUS_API_KEY": "optional", "MORALIS_API_KEY": "optional" } } } } ``` Running `hive` with no subcommand starts the `stdio` MCP server. `hive-mcp` remains available as a backward-compatible binary alias. ## Staying Current The hosted MCP (`https://mcp.hiveintelligence.xyz/mcp`) is managed by Hive. Local `stdio` installs are pinned to whatever your client last fetched, so: - Keep `hive-intelligence@latest` in your client config (as shown above) so each host restart re-resolves the newest version. - Run `hive upgrade` to update a global install and clear the npx cache, then restart your MCP client to load it: ```bash npx -y -p hive-intelligence@latest hive upgrade ``` `hive` checks npm for newer versions once a day and surfaces the result through `hive doctor` and the MCP server instructions, so your agent can prompt you when an update is available. Set `HIVE_NO_UPDATE_CHECK=1` to disable the check. ## Use The CLI Search the catalog: ```bash npx -y -p hive-intelligence@latest hive tools search "token risk" ``` Inspect a schema before execution: ```bash npx -y -p hive-intelligence@latest hive tools info get_price ``` Call a tool from the terminal: ```bash npx -y -p hive-intelligence@latest hive market price --ids bitcoin --vs usd --json ``` Check setup and provider status: ```bash npx -y -p hive-intelligence@latest hive doctor npx -y -p hive-intelligence@latest hive status ``` Generate client config: ```bash npx -y -p hive-intelligence@latest hive config claude-code npx -y -p hive-intelligence@latest hive config codex npx -y -p hive-intelligence@latest hive config cursor npx -y -p hive-intelligence@latest hive config vscode npx -y -p hive-intelligence@latest hive config grok ``` ## How Agents Should Use Hive Hive is designed for retrieval-led agent work: 1. Call `search_tools` or read the compact `hive://toolsets` index. Search returns at most three compact workflow matches by default; use its cursors instead of loading the entire catalog. 2. Load one exact workflow with `hive://toolsets/{id}` or select the compact matching `routes[]` entry returned by `search_tools`. Choose the route whose trigger/question matches the user's decision, preserve its `route_id`, and follow its ordered primary calls, per-call fallback conditions, four-call budget, and stop condition. The broad `coverageCatalog` is capability coverage, not an execution plan. 3. Inspect exact parameters and the endpoint's `operation` for every selected route step with `get_api_endpoint_schema` or `hive tools info`. 4. Execute reads through `invoke_api_endpoint`. For a Hive-native state change, obtain explicit user approval and use `invoke_stateful_endpoint`; clients must not auto-approve that conservatively destructive router. 5. Copy each material call's server-returned `_hive` block into the workflow receipt, map each material `claims[]` entry to exact receipt IDs, account for each canonical `coverage[]` phase, include the selected `route_id`, then call `validate_task_result` before presenting a structured result. Validation checks route membership and order, conditional fallback use, call budget, structure, and consistency; it does not make an invented receipt authentic. 6. Stop when the decision is answerable, a material gap cannot be resolved, or the workflow budget is reached. Report partial evidence instead of silently expanding scope. `search_tools`, `get_api_endpoint_schema`, `validate_task_result`, MCP `tools/list`, and resource reads cost zero Hive credits. Material endpoint executions cost one credit each. Freshness has two layers. `_hive.observed_at` is when Hive first observed the response, or the original cache-population time on a cache hit; `cache_age_ms: 0` means newly retrieved by Hive, not necessarily that the upstream datum is current. Use a provider timestamp, block, slot, transaction, or candle close for source recency. If the provider supplies none, report upstream recency as unknown. The runtime receipt also includes server/build version plus SHA-256 `input_digest` and `result_digest` self-checks. The result check covers the canonical normalized returned payload with the top-level `_hive` block removed. They are not signatures and do not imply a retained receipt lookup. This flow lets an agent answer questions like: - "Is this token safe to buy?" - "What changed in this wallet over the last week?" - "Compare Aave and Curve by TVL, fees, chains, and risk." - "Find active prediction markets for the next Fed decision." - "Show the best pools for this token and explain liquidity risk." - "Remember this wallet monitor and report when important activity changes." ## MCP Contract Root endpoint: ```text https://mcp.hiveintelligence.xyz/mcp ``` Local development endpoint: ```text http://localhost:8080/mcp ``` Root MCP tools: - `search_tools` - `get_api_endpoint_schema` - `invoke_api_endpoint` for read-only endpoints - `invoke_stateful_endpoint` for explicitly approved Hive state changes - `validate_task_result` for structural workflow-output validation ## Stateful Monitoring And B2B State Hive's stateful monitor tools let authenticated agents store durable crypto intelligence intent in Hive instead of relying on chat memory. Direct users get one default state subject per Hive account. B2B partners can use one Hive API key from a trusted backend adapter while isolating downstream customers by signed tenant/end-user subject headers. The stateful surface includes monitor CRUD, stored run reads, observations, alerts, latest snapshots, memory facts, generated reports, and B2B subject admin tools. The scheduled worker runs wallet, token, protocol, market, prediction-market, watchlist digest, token discovery risk, and risk watch workflows. Inspect the exact endpoint schema first. Reads use `invoke_api_endpoint`; creates, updates, archives, remembers, forgets, and alert status changes require explicit user approval and use `invoke_stateful_endpoint`. See [`docs/DOCUMENTATION.md`](docs/DOCUMENTATION.md#stateful-monitoring) for the full monitor, subject-signing, worker, table, and smoke-test contract. The same 10-minute worker also persists current-build provider, MCP protocol, task, and workflow canary evidence in Redis for `/api/health` and `/status`; missing or stale evidence remains `unknown`. For partner products, use [`docs/B2B_PARTNER_ADOPTION.md`](docs/B2B_PARTNER_ADOPTION.md) as the implementation checklist. TypeScript B2B adapters should use `hive-mcp-client/b2b` instead of hand-building subject headers or raw monitor calls. If npm returns 404, publish the client package with [`docs/MCP_CLIENT_RELEASE.md`](docs/MCP_CLIENT_RELEASE.md) before partners depend on it: ```ts import { createHiveB2BAdapter } from "hive-mcp-client/b2b"; const hive = await createHiveB2BAdapter({ apiKey: process.env.HIVE_API_KEY!, subjectSigningSecret: process.env.HIVE_SUBJECT_SIGNING_SECRET!, }); await hive.createWatchlistDigestMonitor( { tenantId: workspaceId, endUserId: userId }, { name: "Daily portfolio brief", target: { wallets, tokens }, cadence: "daily", }, ); ``` Verify a B2B key and signed-subject isolation with: ```bash curl https://mcp.hiveintelligence.xyz/api/v1/b2b/readiness \ -H "Authorization: Bearer $HIVE_API_KEY" ``` ```bash HIVE_API_KEY="hive_live_..." \ HIVE_SUBJECT_SIGNING_SECRET="hive_subject_..." \ npm run smoke:b2b-partner ``` Discovery resources: - `hive://providers` - `hive://categories` - `hive://tools` - `hive://toolsets` - `hive://toolsets/{id}` for one exact workflow, output schema, and execution policy - `hive://task-canaries` - `hive://skills` - `hive://skills/{name}` for one complete procedural skill - `hive://status` Reusable prompts: - `analyze_token` - `compare_protocols` - `portfolio_audit` Category-scoped MCP endpoints remain available for clients that need direct tool lists: - `/hive_market_data/mcp` - `/hive_onchain_dex/mcp` - `/hive_portfolio_wallet/mcp` - `/hive_token_contract/mcp` - `/hive_defi_protocol/mcp` - `/hive_nft_analytics/mcp` - `/hive_security_risk/mcp` - `/hive_network_infrastructure/mcp` - `/hive_search_discovery/mcp` - `/hive_prediction_markets/mcp` ## Providers | Provider | Coverage | Env var | | --------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Alchemy | EVM wallet, token, NFT, transfer, simulation, gas, Solana DAS/Photon, and RPC data | `ALCHEMY_API_KEY` | | CoinGecko | Prices, OHLC, trending, news | Optional `COINGECKO_PRO_API_KEY` or `COINGECKO_DEMO_API_KEY` | | DeFiLlama | TVL, yields, fees, bridges | Free | | CCXT | CEX data, funding rates, perpetuals | Free | | GoPlus | Token, wallet, NFT, approval, phishing, and dApp security | `GOPLUS_APP_KEY` or `GOPLUS_API_KEY`, plus `GOPLUS_APP_SECRET` | | Codex | DEX analytics and Polymarket prediction markets | `CODEX_API_KEY` | | Helius | Solana RPC, DAS, priority fees, wallet history | `HELIUS_API_KEY` | | Moralis | Wallet, token, NFT, PnL, DeFi positions | `MORALIS_API_KEY` | | Tenderly | EVM simulation, tracing, gas estimation, and read-only Node RPC | REST: `TENDERLY_API_KEY` + `TENDERLY_ACCOUNT_SLUG` + `TENDERLY_PROJECT_SLUG`; Node: `TENDERLY_NODE_ACCESS_KEY` or `TENDERLY_GATEWAY_ACCESS_KEY` | | Hyperliquid | Full /info surface: perp/spot markets, order books, user state, vaults, staking, borrow/lend, HIP-4 outcome markets | Free | | Open Data Fetch | Allowlisted, size-capped access to long-tail public crypto APIs | Free | | FRED | US macro indicators (CPI, fed funds, Treasury curve, GDP, unemployment) — government-sourced series allowlist only | `FRED_API_KEY` (free from the St. Louis Fed) | Providers without configured keys remain discoverable and return classified runtime status such as `missing_key`, `plan_required`, `rate_limited`, `degraded`, or `failing` when execution is unavailable. ## REST API Use REST when your app does not speak MCP. List tools: ```bash curl -X GET "https://mcp.hiveintelligence.xyz/api/v1/tools?search=price&limit=20" \ -H "Authorization: Bearer $HIVE_API_KEY" ``` Execute a tool: ```bash curl -X POST https://mcp.hiveintelligence.xyz/api/v1/execute \ -H "Authorization: Bearer $HIVE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tool": "get_price", "args": { "ids": "bitcoin", "vs_currencies": "usd" } }' ``` ## Troubleshooting | Symptom | What to check | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `API key required` | Run `hive auth login`, pass `--api-key`, or set the hosted MCP `Authorization: Bearer ...` header. | | `Unsupported engine` or install failure | Use Node.js 22.12 or newer; Node.js 24 LTS is recommended. | | Hosted MCP works in one client but not another | Confirm whether the client uses custom API-key headers or native OAuth. Native connectors require the hosted OAuth deployment and consent page to be enabled. | | A provider tool returns `missing_key` | The tool is discoverable, but that provider needs an env var such as `ALCHEMY_API_KEY`, `HELIUS_API_KEY`, or `MORALIS_API_KEY`. | | A provider returns `rate_limited`, `degraded`, or `failing` | Check `hive status`, `hive doctor`, or `hive://status` for runtime status and retry guidance. | | `npx` install/cache errors | Retry with a clean cache: `NPM_CONFIG_CACHE=$(mktemp -d) npx -y -p hive-intelligence@latest hive --help`. | ## Develop Locally Install: ```bash npm install ``` Run: ```bash npm run dev # stdio MCP npm run dev:http # HTTP MCP and REST API on :8080 ``` Verify: ```bash npm run check ``` Focused checks: ```bash npm run build npm run test:unit npm run test:mcp-compliance npm run verify:toolsets npm run verify:agent-skills npm run env:render:check ``` ## Package Contents The `hive-intelligence` npm package includes: - `hive`, `hive-intelligence`, `hive-mcp`, and `hive-mcp-server` binaries. - Built MCP server and CLI files in `build/`. - Bundled Hive agent skills in `agent-skills/`. - Local `stdio` MCP runtime for desktop clients and self-hosting. ## Contributor Context Core implementation areas: - `src/mcpServer.ts` builds the MCP servers, tools, resources, prompts, and runtime instructions. - `src/server.ts` runs Express, Streamable HTTP MCP, REST routes, auth, middleware, discovery descriptors, and shutdown. - `src/taskToolsets.ts` defines the workflow surface agents should prefer over raw endpoint browsing. See the [workflow design contract](docs/WORKFLOW_DESIGN.md) for composition and receipt requirements. - `src/cli.ts` and `src/cli/` expose auth, setup, discovery, execution, diagnostics, config generation, aliases, and watch mode. - `agent-skills/` ships agent-installable Hive skills. ## Links - Website: https://www.hiveintelligence.xyz - Hosted MCP: https://mcp.hiveintelligence.xyz/mcp - Public SDK and issues: https://github.com/hive-intel/hive-sdk - Authenticated REST tool catalog: https://mcp.hiveintelligence.xyz/api/v1/tools - Public live catalog overview: https://www.hiveintelligence.xyz/tools/live-catalog - Install guides: https://www.hiveintelligence.xyz/install - Quick start: https://www.hiveintelligence.xyz/quick-start