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

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

Run with npx

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

{
  "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:

{
  "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):

{
  "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

# Build
npm run build

# Run
npm start

License

MIT