Protocols1 min read

Agentic APIs & MCP Server Monetization

Monetizing the Agentic Economy. Bill for tool calls, reasoning tokens, and long-running agent sessions in real time.

Docs  Protocols  MCP Servers

Monetizing the Agentic Economy#

Traditional billing counts API requests. The agentic era demands more. A single agent session may invoke dozens of tools, consume thousands of reasoning tokens, and run for minutes or hours. Aforo is the first monetization platform built for this reality.

Tool-Call Metering

Bill per successful tool execution, not raw HTTP requests

Token Aggregation

Pass through LLM costs (input + output + reasoning) in real time

Session Billing

Orchestrate access and billing for long-running agent threads

 INFO

Aforo treats MCP Servers as a first-class product type — alongside Standard API, Agentic API, and AI Agent. Each has its own metering schema, billing hierarchy, and credential type.

Tool-Call Metering#

Instead of billing per HTTP request, Aforo meters at the tool execution level. When an AI agent calls tools/call via JSON-RPC, the Aforo gateway plugin (or SDK decorator) extracts the tool name, execution status, and duration:

tool-call-event.json

{
  "event_type": "tool_invocation",
  "product_type": "MCP_SERVER",
  "metric_id": "tool_invocations",
  "quantity": 1,
  "properties": {
    "tool_name": "SmartSearch.query",
    "agent_id": "agent_uuid_456",
    "session_id": "session_uuid_789",
    "execution_status": "SUCCESS",
    "execution_duration_ms": 342,
    "cost_tier": "standard"
  }
}

This enables per-tool pricing. Charge $0.001 for a simple lookup, $0.05 for a database write, and $0.10 for an AI-powered analysis — all within the same MCP server subscription.

Reasoning-Token Aggregation#

For AI-powered tools that call LLMs internally, Aforo captures the token breakdown and maps it directly to your COGS:

token-event.json

{
  "event_type": "token_consumption",
  "metric_id": "ai_tokens",
  "quantity": 3200,
  "properties": {
    "input_tokens": 2400,
    "output_tokens": 800,
    "model": "claude-sonnet-4-6",
    "provider": "anthropic",
    "cost_per_1k_input": 0.003,
    "cost_per_1k_output": 0.015,
    "total_provider_cost": 0.0192
  }
}

 WARNING

The total_provider_cost field feeds directly into the Margin Guard. If the provider cost for a tenant's session exceeds their contract revenue, Aforo triggers L1-L3 interventions automatically — before the session accumulates more debt.

Session-Based Billing#

Agent sessions are long-running. A single session may span minutes, invoke 50+ tool calls, and consume thousands of tokens. Aforo tracks the full session lifecycle:

SESSION LIFECYCLE

CREATED → First tool_call detected → session_id assigned
ACTIVE → Tool calls metered, tokens aggregated, duration tracked
IDLE → No activity for 60s → session paused (configurable)
CLOSED → Timeout (1hr default) or explicit close → final billing event

The final billing event consolidates: total tool calls, total tokens, total duration, and total provider cost — allowing you to bill per-session with full COGS attribution.

MCP Server Integration#

Here is how an MCP server integrates with Aforo. The canAccess check runs before every tool execution:

mcp-server-config.json

{
  "mcpServer": {
    "name": "SmartSearch",
    "version": "2.1.0",
    "transport": "stdio",
    "tools": [
      {
        "name": "SmartSearch.query",
        "description": "AI-powered semantic search",
        "monetization": {
          "aforo_product_id": "prod_smartsearch_uuid",
          "aforo_metric_id": "tool_invocations",
          "entitlement_check": true,
          "margin_guard": true,
          "pricing_tier": "standard"
        }
      },
      {
        "name": "SmartSearch.index",
        "description": "Index documents for search",
        "monetization": {
          "aforo_product_id": "prod_smartsearch_uuid",
          "aforo_metric_id": "tool_invocations",
          "entitlement_check": true,
          "margin_guard": true,
          "pricing_tier": "premium"
        }
      }
    ],
    "aforo": {
      "api_key": "{AFORO_API_KEY}",
      "tenant_id_source": "request.headers.x-tenant-id",
      "session_timeout_ms": 3600000,
      "batch_size": 50,
      "credential_type": "CLIENT_CREDENTIALS"
    }
  }
}

SDK Integration (Decorator Pattern)#

For MCP servers built with our SDKs, use the wrapToolHandler decorator to automatically meter every tool call:

Node.js

mcp-server.js

const { AforoBilling } = require('@aforo/mcp-metering');

const billing = new AforoBilling({
  apiKey: process.env.AFORO_API_KEY,
  productId: 'prod_smartsearch_uuid',
});

// Wrap any tool handler — timing, metering, and entitlements are automatic
server.setRequestHandler('tools/call', billing.wrapToolHandler(
  async (request) => {
    const { name, arguments: args } = request.params;
    // Your tool logic here
    return { content: [{ type: 'text', text: result }] };
  }
));

Python

mcp_server.py

from aforo_mcp_metering import AforoBilling

billing = AforoBilling(
    api_key=os.environ["AFORO_API_KEY"],
    product_id="prod_smartsearch_uuid",
)

# Async decorator — tracks timing, tokens, and entitlements
@billing.wrap_tool_handler
async def handle_tool_call(request):
    tool_name = request["params"]["name"]
    args = request["params"]["arguments"]
    # Your tool logic here
    return {"content": [{"type": "text", "text": result}]}

Billing Hierarchy#

MCP Server billing follows the same hierarchy as all Aforo product types:

Customer → Team → Agent → API Key
Usage tracked at Session level. Keys assigned at Agent level. Credential type: CLIENT_CREDENTIALS.

Product TypeHierarchyUsage LevelCredential

Standard APICustomer → Team → AppApp InstanceBEARER_TOKEN

Agentic APICustomer → Team → AppApp InstanceBEARER_TOKEN

AI AgentCustomer → Team → AgentAgent SessionCLIENT_CREDENTIALS

MCP ServerCustomer → Team → AgentSessionCLIENT_CREDENTIALS

 PRO TIP

MCP Server is the 4th GA product type in Aforo. It uses the same pricing engine, billing pipeline, and storefront infrastructure as Standard APIs — but with session-aware metering and tool-level pricing granularity built in.