Stdio Mode

Stdio mode is for MCP servers running locally via stdio transport -- the standard integration pattern for Claude Code, local CLI agents, and other tools that run on the user's machine.

Authentication

Stdio mode uses the customer's HiveForge API key for authentication. Pass it as a Bearer token in the Authorization header.

Authorization: Bearer hf_live_a1b2c3d4e5f6g7h8i9j0...

The API key is tied to an organization. The platform automatically resolves the organization to its active deployment and entitlement tier.

Stdio endpoints do not require the X-MCP-Service-Key header. They are designed for direct use by customer-facing MCP servers.

Endpoints

All endpoints use the base URL: https://api.hiveforge.dev/api/v1/mcp

Check Entitlement

Verify whether the caller is entitled to use a specific MCP tool before executing it.

POST /api/v1/mcp/stdio/check-entitlement

Request Body

Field	Type	Required	Description
`tool_name`	`string`	Yes	MCP tool name (e.g., `hornethive_execute_crew`)

Response

Field	Type	Description
`allowed`	`boolean`	Whether the tool call is permitted
`credit_cost`	`integer`	Credits that will be deducted
`tier`	`string\|null`	Deployment's entitlement tier
`reason`	`string\|null`	Denial reason if `allowed` is `false`

Reason codes: sandbox_tier, insufficient_credits, no_deployment_found, deployment_not_found, mcp_disabled

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": "hornethive_execute_crew"
  }'

Example response (allowed):

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

Example response (denied):

{
  "allowed": false,
  "credit_cost": 0,
  "tier": "sandbox",
  "reason": "sandbox_tier"
}

Record Usage

Record a completed MCP tool invocation and deduct credits. Call this after the tool executes successfully.

POST /api/v1/mcp/stdio/record-usage

Request Body

Field	Type	Required	Description
`tool_name`	`string`	Yes	MCP tool name that was executed
`metadata`	`object\|null`	No	Arbitrary metadata for the audit trail

Response

Field	Type	Description
`success`	`boolean`	Whether credits were deducted
`credits_used`	`integer`	Number of credits deducted
`credits_remaining`	`integer\|null`	Remaining credit balance

curl -X POST https://api.hiveforge.dev/api/v1/mcp/stdio/record-usage \
  -H "Authorization: Bearer hf_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "hornethive_execute_crew",
    "metadata": {
      "crew_id": "content-pipeline",
      "duration_ms": 4520
    }
  }'

Example response:

{
  "success": true,
  "credits_used": 5,
  "credits_remaining": 9450
}

Full Integration Example

Here is a complete example of metering an MCP tool call using the stdio endpoints:

import httpx
 
API_URL = "https://api.hiveforge.dev/api/v1/mcp"
API_KEY = "hf_live_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
 
 
async def metered_tool_call(tool_name: str, execute_fn, **kwargs):
    """Execute an MCP tool with entitlement checking and usage recording."""
    async with httpx.AsyncClient() as client:
        # Step 1: Check entitlement
        check = await client.post(
            f"{API_URL}/stdio/check-entitlement",
            headers=HEADERS,
            json={"tool_name": tool_name},
        )
        check_data = check.json()
 
        if not check_data["allowed"]:
            return {
                "error": f"Tool denied: {check_data['reason']}",
                "tier": check_data.get("tier"),
            }
 
        # Step 2: Execute the tool
        result = await execute_fn(**kwargs)
 
        # Step 3: Record usage
        await client.post(
            f"{API_URL}/stdio/record-usage",
            headers=HEADERS,
            json={"tool_name": tool_name, "metadata": {"args": kwargs}},
        )
 
        return result

⚠️

Always check entitlement before executing the tool. If you record usage without checking first, the credit deduction may fail for depleted accounts, but the tool will have already run.

Setup Guide Service-to-Service