MCP Credit Costs

Every MCP tool call consumes credits based on the action type. This page documents the credit cost structure, how to look up costs dynamically, and how credit packs work.

Credit Cost Table

Each tool name maps to a credit action. Tools within the same action category share the same cost.

Credit Action	Mapped Tools	Description
`task_basic`	`taskcrush_list_tasks`, `taskcrush_create_task`, `taskcrush_update_task`, `taskcrush_list_goals`, `taskcrush_create_goal`, `hiveforge_delete_instance`, `hiveforge_redeploy_instance`	Basic CRUD operations
`task_advanced`	`taskcrush_chat`, `hiveforge_create_instance`, `hiveforge_promote_instance`	Operations involving AI or complex orchestration
`crew_execute`	`hornethive_execute_crew`	Multi-agent crew execution
`generate`	`hornethive_generate`	Content generation
`rag_query`	`hornethive_rag_search`	RAG vector search
`rag_ingest`	`hornethive_ingest`	RAG document ingestion
`tao_trace`	`taodata_log_trace`	Observability trace logging
`tao_evaluate`	`taodata_evaluate`	AI evaluation runs
`tao_analytics`	`taodata_get_analytics`, `taodata_search_traces`	Analytics and trace search
`platform_basic`	`hiveforge_list_templates`, `hiveforge_list_instances`, `hiveforge_get_instance`, `hiveforge_get_pipeline_status`, `hiveforge_get_instance_health`	Read-only platform queries

Actual credit values are configured in the database and can be retrieved at runtime via the /credit-costs endpoint. The table above shows the action categories, not fixed prices.

Looking Up Costs at Runtime

Use the credit costs endpoint to get current prices:

curl https://api.hiveforge.dev/api/v1/mcp/credit-costs \
  -H "X-MCP-Service-Key: your-shared-secret-key"

Response:

{
  "costs": [
    { "action": "task_basic", "credits": 1, "description": null },
    { "action": "task_advanced", "credits": 3, "description": null },
    { "action": "crew_execute", "credits": 5, "description": null },
    { "action": "generate", "credits": 3, "description": null },
    { "action": "rag_query", "credits": 2, "description": null },
    { "action": "rag_ingest", "credits": 2, "description": null },
    { "action": "tao_trace", "credits": 1, "description": null },
    { "action": "tao_evaluate", "credits": 3, "description": null },
    { "action": "tao_analytics", "credits": 2, "description": null },
    { "action": "platform_basic", "credits": 1, "description": null }
  ]
}

Cache this response for up to 1 hour. Credit costs change infrequently.

How Credits Work

Monthly Allocation

Each tier includes a monthly credit allocation that resets at the billing period boundary. Credits from the monthly allocation do not roll over.

Purchased Credits

Credit packs can be purchased separately. Purchased credits are consumed after the monthly allocation is exhausted and do persist across billing periods.

Deduction Order

When a tool call is recorded, credits are deducted in this order:

Monthly allocation (period balance) -- used first
Purchased credits (purchased balance) -- used when period balance is zero

Overage Handling

When credits are exhausted, the behavior depends on the deployment's overage mode:

Mode	Behavior
`block`	Tool calls are denied with `insufficient_credits`
`allow`	Tool calls proceed; balance goes negative (tracked for invoicing)
`auto_purchase`	A pre-configured credit pack is automatically purchased and credits are added

Monitoring Credit Usage

Check Balance

Use the entitlement check response to monitor available credits. The credits_available field (service-to-service mode) shows the current balance.

Usage Summary

The credit usage summary endpoint provides aggregated usage data by service and action:

curl "https://api.hiveforge.dev/api/v1/credits/usage?deployment_id=YOUR_DEPLOYMENT_ID" \
  -H "Authorization: Bearer hf_live_your_key_here"

Cost Estimation

To estimate costs before executing a batch of tool calls:

async def estimate_batch_cost(tool_names: list[str], credit_costs: dict) -> int:
    """Estimate total credit cost for a batch of tool calls."""
    total = 0
    for tool in tool_names:
        # Map tool name to action (simplified; real mapping is in TOOL_ACTION_MAP)
        action = get_action_for_tool(tool)
        total += credit_costs.get(action, 1)  # default to 1 credit
    return total
 
# Example
costs = await fetch_credit_costs()
cost_map = {c["action"]: c["credits"] for c in costs["costs"]}
estimated = await estimate_batch_cost(
    ["taskcrush_create_task", "hornethive_execute_crew", "taodata_evaluate"],
    cost_map,
)
print(f"Estimated cost: {estimated} credits")
# Output: Estimated cost: 9 credits (1 + 5 + 3)

Unknown Tools

If a tool name is not in the TOOL_ACTION_MAP, it defaults to the platform_basic action. This ensures all tool calls are metered even if the mapping has not been explicitly configured.

Entitlements Overview