hive-mcp-client

Typed TypeScript adapter for building applications on Hive MCP.

Use this package for TypeScript backends, Next.js routes, agent services, cron jobs, and framework adapters that need MCP discovery, schema lookup, endpoint invocation, Vercel AI SDK adapters, LangChain adapters, or B2B subject sessions. Non-TypeScript stacks, constrained runtimes, and low-level debugging can use the REST API directly.

Install

npm install hive-mcp-client

Public source and docs: https://github.com/hive-intel/hive-sdk/tree/main/client

Hosted MCP endpoint:

https://mcp.hiveintelligence.xyz/mcp

Set the key server-side:

export HIVE_API_KEY="hive_live_..."

For B2B partner setup, install the controlled adapter tarball in the backend project and run the local doctor before writing integration code:

export HIVE_SUBJECT_SIGNING_SECRET="hive_subject_..."
./node_modules/.bin/hive-mcp doctor \
  --tenant-id workspace_123 \
  --end-user-id user_456

The doctor checks the readiness endpoint, verifies that the key is B2B-enabled, confirms the local signing secret is present, and validates subject header signing without printing either secret.

Quick Start

import {
  createHiveMcpClient,
  invokeHiveEndpoint,
} from "hive-mcp-client";

const hive = await createHiveMcpClient({
  apiKey: process.env.HIVE_API_KEY,
  clientName: "my-app",
});

try {
  const result = await invokeHiveEndpoint(hive, "get_price", {
    ids: "bitcoin",
    vs_currencies: "usd",
  });

  console.log(result.json ?? result.text);
} finally {
  await hive.close();
}

searchHiveTools, getHiveEndpointSchema, and invokeHiveEndpoint already return normalized results with isError, json, text, raw, and optional structuredContent. Use normalizeHiveToolResult only when you call client.callTool() directly.

Never pass a full Hive API key to browser code. Browser UI should call your own server route, and that route should use this package.

B2B Subject Sessions

B2B partners should keep one Hive API key on their backend and isolate each downstream customer with signed subject context. Do not ask every downstream customer to create a Hive key.

State is scoped by Hive owner plus resolved subject, not by browser session and not only by API key. Derive tenantId and endUserId from trusted partner auth state on the server.

const hive = await createHiveMcpClient({
  apiKey: process.env.HIVE_API_KEY,
  subjectSigningSecret: process.env.HIVE_SUBJECT_SIGNING_SECRET,
  clientName: "my-agent-backend",
});

const customerHive = hive.withSubject({
  tenantId: "workspace_123",
  endUserId: "user_456",
});

await customerHive.callTool("hive_create_monitor", {
  kind: "watchlist_digest",
  name: "Daily portfolio brief",
  target: {
    wallets: ["0x..."],
    tokens: ["bitcoin"],
  },
  cadence: "daily",
});

For request-scoped adapters, pass the subject per call:

await hive.callTool(
  "hive_list_monitors",
  {},
  {
    subject: {
      tenantId: request.workspaceId,
      endUserId: request.userId,
    },
  },
);

The adapter signs X-Hive-Tenant-Id, X-Hive-End-User-Id, X-Hive-Subject-Timestamp, and X-Hive-Subject-Signature for the MCP request. Hive stores state under the authenticated Hive account plus the resolved subject, so monitors, memory, alerts, and reports stay isolated per downstream customer.

B2B Product Adapter

For partner products, prefer the B2B adapter helpers over raw tool calls for the first user-facing workflows:

import {
  checkHiveB2BReadiness,
  createHiveB2BAdapter,
} from "hive-mcp-client/b2b";

const readiness = await checkHiveB2BReadiness({
  apiKey: process.env.HIVE_API_KEY!,
});

if (!readiness.b2b_adapter_ready) {
  throw new Error(readiness.warnings.join(" "));
}

const hive = await createHiveB2BAdapter({
  apiKey: process.env.HIVE_API_KEY!,
  subjectSigningSecret: process.env.HIVE_SUBJECT_SIGNING_SECRET!,
  clientName: "partner-api",
});

const subject = {
  tenantId: session.workspaceId,
  endUserId: session.userId,
};

await hive.createWatchlistDigestMonitor(subject, {
  cadence: "daily",
  name: "Daily portfolio brief",
  target: {
    tokens: ["bitcoin", "ethereum"],
    wallets: ["0x..."],
  },
});

await hive.createRiskWatchMonitor(subject, {
  name: "Wallet and approvals risk",
  target: {
    addresses: ["0x..."],
    chains: ["ethereum", "base"],
  },
});

await hive.rememberFact(subject, {
  key: "report_style",
  namespace: "watchlist_digest",
  value: { detail: "concise", riskTolerance: "low" },
});

const alerts = await hive.listAlerts(subject, { status: "open", limit: 20 });

The adapter intentionally covers the common B2B product actions: watchlist digests, risk watches, token discovery risk, alerts, reports, and memory facts, plus monitor cleanup and subject audit reads for support. Use callForSubject() when you need an advanced Hive tool that does not have a convenience wrapper yet.

Discovery Flow

Hive root MCP exposes a compact tool surface. Discover the task first, inspect the exact schema, then invoke the endpoint:

import {
  createHiveMcpClient,
  getHiveEndpointSchema,
  invokeHiveEndpoint,
  readHiveMetadataSnapshot,
  searchHiveTools,
} from "hive-mcp-client";

const hive = await createHiveMcpClient({
  apiKey: process.env.HIVE_API_KEY,
});

const matches = await searchHiveTools(hive, {
  query: "wallet approvals risk",
  limit: 10,
});

const schema = await getHiveEndpointSchema(hive, "get_address_risk");
const response = await invokeHiveEndpoint(hive, "get_address_risk", {
  address: "0x...",
  chain: "eth",
});

const metadata = await readHiveMetadataSnapshot(hive);
await hive.close();

Preserve _hive, meta, provider, source, freshness, cache, and runtime status fields in your own response model. Do not silently strip these fields before showing data to a user or downstream agent.

Next.js Route Example

import { NextResponse } from "next/server";
import { createHiveMcpClient, invokeHiveEndpoint } from "hive-mcp-client";

export async function GET() {
  const hive = await createHiveMcpClient({
    apiKey: process.env.HIVE_API_KEY,
    clientName: "my-next-app",
  });

  try {
    const price = await invokeHiveEndpoint(hive, "get_price", {
      ids: "bitcoin,ethereum",
      vs_currencies: "usd",
    });

    return NextResponse.json({ ok: true, price });
  } finally {
    await hive.close();
  }
}

Runtime Controls

const hive = await createHiveMcpClient({
  apiKey: process.env.HIVE_API_KEY,
  connectTimeoutMs: 18_000,
  requestTimeoutMs: 22_000,
  retry: {
    attempts: 2,
    baseDelayMs: 500,
  },
});

The client retries MCP tool calls with exponential backoff. Treat invalid schemas, missing keys, and user input errors as non-retryable in your own app logic.

Metadata And Sources

import {
  extractHiveSources,
  inferHiveProvider,
  readHiveMetadataSnapshot,
} from "hive-mcp-client";

const snapshot = await readHiveMetadataSnapshot(hive);
const provider = inferHiveProvider("get_price", snapshot);
const sources = extractHiveSources({
  endpointName: "get_price",
  result,
  snapshot,
});

Use metadata to explain where data came from, whether it was cached or degraded, and when it was fetched.

Vercel AI SDK

import {
  buildAiSdkHiveMcpTransportConfig,
  prepareHiveAiSdkTools,
} from "hive-mcp-client/ai-sdk";

const transport = buildAiSdkHiveMcpTransportConfig({
  apiKey: process.env.HIVE_API_KEY,
});

const { tools } = await prepareHiveAiSdkTools({
  client: myAiSdkMcpClient,
  query: "token diligence",
  selectionMode: "ranked",
});

Use ranked or core tool selection to avoid flooding the model with unnecessary category tools.

LangChain

The LangChain bridge uses @langchain/core as an optional peer dependency. Install it only in apps that use the /langchain export:

npm install hive-mcp-client @langchain/core

import { createHiveLangChainTools } from "hive-mcp-client/langchain";

const tools = createHiveLangChainTools({
  clientOptions: {
    apiKey: process.env.HIVE_API_KEY,
  },
});

The LangChain bridge creates tools over the compact Hive root surface and uses Hive discovery helpers for endpoint invocation.

REST Fallback

REST is still supported and useful outside TypeScript:

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"
    }
  }'

Package Status

hive-mcp-client is published on npm as the public TypeScript adapter for Hive MCP. The release gate below is the canonical flow for cutting a public version.

Release gate:

npm --workspace hive-mcp-client run typecheck
npm --workspace hive-mcp-client run test
npm --workspace hive-mcp-client run pack:check
npm publish --workspace hive-mcp-client --access public

Public source: https://github.com/hive-intel/hive-sdk/tree/main/client