npm package: @journeyrewards/hive-mcp-server
Description: MCP server for Journey Hive Agent Orchestration — use with Claude Desktop, Cursor, and other MCP clients
Latest version: 1.2.1

# Journey Hive MCP Server

Model Context Protocol (MCP) server for Journey Hive Agent Orchestration. Enables AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients to interact with your Journey Hive agent swarm.

## Installation

### Global Install

```bash
npm install -g @journeyrewards/hive-mcp-server
```

### Run with npx

```bash
npx @journeyrewards/hive-mcp-server
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|---|---|---|
| `JOURNEY_HIVE_API_KEY` | Your Journey Hive API key (format: `jh_live_...` or `jh_test_...`) | Required |
| `JOURNEY_HIVE_BASE_URL` | Base URL for the Journey Hive API | `https://journey-hive.replit.app` |

### Claude Desktop

Add the following to your `claude_desktop_config.json`:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "journey-hive": {
      "command": "npx",
      "args": ["@journeyrewards/hive-mcp-server"],
      "env": {
        "JOURNEY_HIVE_API_KEY": "jh_live_your_api_key_here",
        "JOURNEY_HIVE_BASE_URL": "https://journey-hive.replit.app"
      }
    }
  }
}
```

If installed globally:

```json
{
  "mcpServers": {
    "journey-hive": {
      "command": "hive-mcp",
      "env": {
        "JOURNEY_HIVE_API_KEY": "jh_live_your_api_key_here"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json` in your project or global config):

```json
{
  "mcpServers": {
    "journey-hive": {
      "command": "npx",
      "args": ["@journeyrewards/hive-mcp-server"],
      "env": {
        "JOURNEY_HIVE_API_KEY": "jh_live_your_api_key_here"
      }
    }
  }
}
```

## Available Tools

| Tool | Description | Required Parameters |
|---|---|---|
| `send_message` | Send a message to an agent and get a response | `message` (agent_id optional if default configured) |
| `create_conversation` | Create a new conversation with an agent | None (agent_id optional if default configured) |
| `list_conversations` | List conversations, optionally filtered by agent | None |
| `get_conversation` | Get details of a specific conversation | `conversation_id` |
| `get_conversation_messages` | Get all messages in a conversation | `conversation_id` |
| `list_agents` | List all available agents | None |
| `get_agent` | Get details of a specific agent | `agent_id` |
| `update_agent_soul` | Update an agent's soul template or personality | `agent_id` |
| `get_usage` | Get API usage statistics | None |

### Tool Details

#### send_message
Send a message to a Journey Hive agent. Optionally continue an existing conversation or use streaming.

```
Parameters:
  - agent_id (string, required): The agent ID
  - message (string, required): The message text
  - conversation_id (string, optional): Continue an existing conversation
  - stream (boolean, optional): Use streaming mode
```

#### create_conversation
Create a new conversation thread with an agent.

```
Parameters:
  - agent_id (string, required): The agent ID
  - external_user_id (string, optional): External user identifier
```

#### list_conversations
List conversations with optional filters.

```
Parameters:
  - agent_id (string, optional): Filter by agent
  - limit (number, optional): Max results to return
```

#### update_agent_soul
Update an agent's personality and behavior configuration.

```
Parameters:
  - agent_id (string, required): The agent ID
  - soul_template (string, optional): New soul template
  - personality_notes (string, optional): New personality notes
```

#### get_usage
Get API usage statistics over a time period.

```
Parameters:
  - days (number, optional): Number of days to look back (default: 7)
```

## Available Resources

| URI Pattern | Description |
|---|---|
| `agent://{agent_id}` | Returns agent details as JSON |
| `conversation://{conversation_id}` | Returns conversation with all messages |

## Available Prompts

| Prompt | Description | Parameters |
|---|---|---|
| `chat_with_agent` | Send a message and get a formatted response | `agent_id`, `message` |
| `analyze_conversation` | Analyze conversation history | `conversation_id` |

## Development

```bash
# Build
npm run build

# Run
npm start
```

## License

MIT