MCP Setup Guide

This guide walks through connecting your MCP server to HiveForge for metered tool usage.

Prerequisites

• A HiveForge deployment on the Trial tier or above
• An MCP server implementing the Model Context Protocol
• Access to the HiveForge dashboard for credential management

Step 1: Choose Your Integration Mode

Step 2: Get Credentials

Stdio Mode Credentials

Generate an API key from your HiveForge dashboard. The key follows the format hf_live_... and is tied to your organization.

1. Go to Settings > API Keys in the HiveForge dashboard
2. Click Create API Key
3. Copy the key -- it will not be shown again

Service-to-Service Credentials

For hosted MCP servers, you need a shared service key configured on both the HiveForge API and your MCP server.

1. Set the HIVEFORGE_MCP_SERVICE_KEY environment variable on the HiveForge API
2. Use the same value as the X-MCP-Service-Key header in your MCP server's requests

Step 3: Configure Environment Variables

HIVEFORGE_API_URL=https://api.hiveforge.dev
HIVEFORGE_API_KEY=hf_live_a1b2c3d4e5f6g7h8i9j0...

Step 4: Register Your MCP Tools

HiveForge uses a tool-name-to-action mapping to determine credit costs. Your tool names must match the registered names in the platform. The current registered tools are:

# TaskCrush
taskcrush_list_tasks, taskcrush_create_task, taskcrush_update_task,
taskcrush_list_goals, taskcrush_create_goal, taskcrush_chat

# HornetHive
hornethive_execute_crew, hornethive_generate,
hornethive_rag_search, hornethive_ingest

# Tao-Data
taodata_log_trace, taodata_evaluate,
taodata_get_analytics, taodata_search_traces

# HiveForge Platform
hiveforge_list_templates, hiveforge_list_instances, hiveforge_get_instance,
hiveforge_create_instance, hiveforge_delete_instance, hiveforge_redeploy_instance,
hiveforge_get_pipeline_status, hiveforge_promote_instance, hiveforge_get_instance_health

Step 5: Test the Connection

curl -X POST https://api.hiveforge.dev/api/v1/mcp/stdio/check-entitlement \
  -H "Authorization: Bearer hf_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "taskcrush_list_tasks"}'

{
  "allowed": true,
  "credit_cost": 1,
  "tier": "launch",
  "reason": null
}

Integration Flow

Once connected, your MCP server should follow this flow for every tool call:

1. Check entitlement before executing the tool
2. Execute the tool only if allowed is true
3. Record usage after successful execution
4. Handle denials gracefully when allowed is false

See Entitlements for detailed guidance on handling the entitlement flow.

Troubleshooting