---
title: Package Architecture
lastUpdated: '2026-06-03'
nextjs:
  metadata:
    title: "Hive Package Architecture - MCP, REST, CLI, and TypeScript Adapter"
    description: "Understand which Hive package, transport, and endpoint to use across remote MCP clients, REST backends, the CLI, local stdio, and the TypeScript adapter."
    alternates:
      canonical: https://www.hiveintelligence.xyz/installation
    keywords: "hive package architecture, hive-intelligence npm package, hive-mcp-client, hive cli, hive mcp package"
---

Use this page when you need to choose the right Hive package, transport, or endpoint for a production integration. For first-run setup, start with [Get Started](/get-started) or [Install Hive](/install).

{% ai-doc-actions path="/installation" title="Package Architecture" /%}

---

## Package surfaces

Remote MCP and REST are hosted at `mcp.hiveintelligence.xyz`; local MCP stdio and terminal workflows ship in **`hive-intelligence`**. Custom TypeScript applications can use the official **`hive-mcp-client`** adapter, published on npm at v0.1.5 (`npm install hive-mcp-client`); its source is public in the [`hive-intel/hive-sdk`](https://github.com/hive-intel/hive-sdk) repo under `client/`. REST remains the stable path for non-TypeScript stacks and low-level integrations.

| Surface | Entrypoint | Used by |
|---|---|---|
| Remote MCP server | `https://mcp.hiveintelligence.xyz/mcp` | Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Codex CLI, Gemini CLI, OpenAI Responses API, and header-capable MCP clients |
| MCP stdio wrapper | `npx -y -p hive-intelligence@latest hive` | Clients or networks that require a local subprocess instead of remote Streamable HTTP |
| TypeScript app adapter | `npm install hive-mcp-client` then `import { createHiveMcpClient } from 'hive-mcp-client'` | Node and backend apps that embed Hive MCP |
| `hive` CLI | `npx -y -p hive-intelligence@latest hive …` (named bin) | Terminal workflows, scripts, and cron jobs |

The local executable is named `hive`, which differs from the package name, so `npx` uses `-p hive-intelligence@latest` to pick the package and then `hive` as the binary.

---

## Remote MCP clients

Configure Hive as an MCP server in your AI client. The managed endpoint is `https://mcp.hiveintelligence.xyz/mcp`, and the recommended transport is remote Streamable HTTP wherever the client supports it.

### Claude Desktop

Claude Desktop adds remote MCP servers through its Custom Connectors UI, not through `claude_desktop_config.json`.

```text
Name: Hive
URL: https://mcp.hiveintelligence.xyz/mcp
Authentication: Bearer token
Token: YOUR_HIVE_API_KEY
```

Use the stdio fallback in [the Claude Desktop guide](/install/claude-desktop) only when you need a local subprocess.

### Cursor

Open Cursor Settings, navigate to **MCP**, and add a new remote server with this config:

```json
{
  "mcpServers": {
    "hive": {
      "url": "https://mcp.hiveintelligence.xyz/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_HIVE_API_KEY"
      }
    }
  }
}
```

### VS Code

Add this to `.vscode/mcp.json`:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "hive-api-key",
      "description": "Hive API Key",
      "password": true
    }
  ],
  "servers": {
    "hive": {
      "type": "http",
      "url": "https://mcp.hiveintelligence.xyz/mcp",
      "headers": {
        "Authorization": "Bearer ${input:hive-api-key}"
      }
    }
  }
}
```

For Windsurf, Gemini CLI, OpenAI Responses API, Codex CLI, and stdio fallback configs, use the dedicated [install guide](/install) or the unified [setup page](/setup).

---

## REST API

REST has no client package. Send a POST request directly:

```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 payload keys are `tool` and `args`. See the [API Integration](/api-integration) page for the full REST reference.

---

## TypeScript MCP client

The typed adapter is published on npm as `hive-mcp-client@0.1.5`; its source is mirrored in [`hive-intel/hive-sdk`](https://github.com/hive-intel/hive-sdk) under `client/`. Install it from npm:

```bash
npm install hive-mcp-client
```

```ts
import {
  createHiveMcpClient,
  invokeHiveEndpoint,
} from 'hive-mcp-client';

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

const prices = await invokeHiveEndpoint(hive, 'get_price', {
  ids: 'bitcoin,ethereum',
  vs_currencies: 'usd',
});

console.log(prices.json ?? prices.text);
```

The adapter keeps custom apps on the same discovery/schema/execution path as MCP agents. For non-TypeScript stacks, use the [REST API](/api-integration) directly.

The current adapter source includes:

- core MCP helpers such as `createHiveMcpClient`, `searchHiveTools`, `getHiveEndpointSchema`, `invokeHiveEndpoint`, `normalizeHiveToolCall`, `rankHiveCategoriesForQuery`, `normalizeHiveToolResult`, and `readHiveMetadataSnapshot`
- `hive-mcp-client/b2b` for signed subject sessions, B2B readiness checks, `hive-mcp doctor`, and adapter methods for watchlist digest monitors, risk watches, token discovery risk, alerts, reports, memory facts, monitor cleanup, `forSubject()`, `callForSubject()`, and subject audit reads
- `hive-mcp-client/ai-sdk` for Vercel AI SDK MCP transport config and ranked/core/all tool selection
- `hive-mcp-client/langchain` for LangChain tools over Hive's compact root MCP surface; install `@langchain/core` only in apps that use this export

`searchHiveTools`, `getHiveEndpointSchema`, and `invokeHiveEndpoint` already return normalized results. Use `normalizeHiveToolResult` only when your code calls `client.callTool()` directly.

Keep `HIVE_API_KEY` and `HIVE_SUBJECT_SIGNING_SECRET` in server-side runtime config. Browser code should call your own backend instead of importing the adapter directly.

---

## CLI

Run tools from the terminal through the published npm package. The package is `hive-intelligence` and the executable is `hive`, so npx needs `-p` to pick the package before naming the binary:

```bash
HIVE_API_KEY=YOUR_KEY npx -y -p hive-intelligence@latest hive market price --ids bitcoin --vs usd
```

Or install globally and call `hive` directly:

```bash
npm install -g hive-intelligence
hive auth login
hive market price --ids bitcoin --vs usd
```

See the [CLI Reference](/cli) for all available commands.

---

## Get Your API Key

1. Go to [/dashboard/keys](/dashboard/keys)
2. Enter your email address
3. Open the sign-in link sent to your inbox
4. Copy your API key from the dashboard

The email sign-in flow is passwordless. After you confirm the email link, copy your API key from the dashboard.

---

## Next Steps

- [Install Hive](/install) - connect a supported AI client
- [Quick Start](/quick-start) - verify your setup with a live request
- [API Integration](/api-integration) - exact REST and MCP request contracts
- [MCP Integration Tutorial](/tutorials/mcp-integration) - connect Hive to an AI agent step by step
- [Playground](/playground) - explore tools interactively