MCP Integration
Overview

MCP Integration

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. HiveForge provides first-class MCP integration, allowing your deployed applications to meter, gate, and monetize MCP tool usage through the platform's credit system.

Why MCP Matters

MCP enables AI agents (such as Claude Code, custom LLM pipelines, or hosted assistants) to call external tools in a standardized way. Without a metering layer, these tool calls run untracked and ungated. HiveForge sits between the agent and the tools to provide:

  • Entitlement checking -- gate tool access by subscription tier
  • Credit-based metering -- charge per tool invocation based on action type
  • Usage recording -- full audit trail of every tool call
  • Graceful degradation -- agents receive structured denial reasons they can act on

Two Integration Modes

HiveForge supports two modes depending on where your MCP server runs:

ModeUse CaseAuth Method
StdioLocal agents (Claude Code, CLI tools)API key (Authorization: Bearer hf_live_...)
Service-to-ServiceHosted MCP serversShared secret (X-MCP-Service-Key header)

Stdio Mode

For MCP servers running locally via stdio transport (e.g., Claude Code connecting to your tools on the user's machine). The MCP server authenticates with the customer's HiveForge API key and calls the stdio metering endpoints directly.

Read the Stdio Mode guide

Service-to-Service Mode

For hosted MCP servers that run alongside your application. The MCP server authenticates with a shared service key and has access to the full resolution, entitlement, and usage API.

Read the Service-to-Service guide

Architecture

                         ┌──────────────────────┐
                         │     AI Agent          │
                         │  (Claude Code, etc.)  │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │     MCP Server        │
                         │  (stdio or hosted)    │
                         └──────────┬───────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
            ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
            │  1. Check    │ │  2. Execute  │ │  3. Record   │
            │  Entitlement │ │  Tool        │ │  Usage       │
            └──────┬───────┘ └──────────────┘ └──────┬───────┘
                   │                                  │
                   ▼                                  ▼
            ┌─────────────────────────────────────────────────┐
            │              HiveForge API                      │
            │         https://api.hiveforge.dev               │
            ├─────────────────────────────────────────────────┤
            │  Entitlements  │  Credits  │  Usage Tracking    │
            └─────────────────────────────────────────────────┘

Metered Tool Families

HiveForge meters tools across several product families:

FamilyToolsExample
TaskCrush6 toolstaskcrush_create_task, taskcrush_chat
HornetHive4 toolshornethive_execute_crew, hornethive_rag_search
Tao-Data4 toolstaodata_log_trace, taodata_evaluate
HiveForge Platform9 toolshiveforge_list_templates, hiveforge_create_instance

Each tool maps to a credit action with a specific cost. See Credit Costs for the full breakdown.

MCP integration requires the Trial tier or above. Sandbox-tier deployments receive a structured sandbox_tier denial when attempting MCP tool calls.

Next Steps

API ReferenceSetup Guide