1 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.

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 a session's provider cost exceeds the contract revenue behind it, 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

ACTIVE → First tool_call assigns a session_id; tool calls metered, tokens aggregated, duration tracked
TIMED_OUT → No activity past the idle timeout (default 3,600s / 1 hr) → session closed automatically
COMPLETED → Explicit close → session closed cleanly
FAILED → Session ended in error

TIMED_OUT, COMPLETED, and FAILED are terminal. Each tool call is metered as it happens; the session record consolidates total tool calls, tokens, duration, and provider cost for 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 { AforoMcpBilling } = require('@aforo/mcp-metering');

const billing = new AforoMcpBilling({
  tenantId: process.env.AFORO_TENANT_ID,
  productId: 'prod_smartsearch_uuid',
  apiKey: process.env.AFORO_API_KEY,
  ingestorUrl: 'https://ingest.aforo.ai',   // all four are required
});

// 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 AforoMcpBilling

billing = AforoMcpBilling(
    tenant_id=os.environ["AFORO_TENANT_ID"],
    product_id="prod_smartsearch_uuid",
    api_key=os.environ["AFORO_API_KEY"],
    ingestor_url="https://ingest.aforo.ai",   # all four are required
)

# 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.

What this guide does NOT cover#

This page walks the on-the-wire side of MCP metering — how a tools/call becomes a billable event, how sessions are tracked, and how the gateway plugins + SDK decorators emit that data. It does not cover:

Creating an MCP Server product in your catalog, wiring the tool registry, and choosing transport/integration mode — see MCP Server (Catalog).
Pricing model choices per tool (per-tool multipliers via dimensionPricing) — same page.
Which billable units to attach to an MCP Server product — see Billable Units.
End-customer registration of agents and rotation of client credentials — see Customers.
Operator-side MCP analytics dashboards. Those live inside the Aforo product console, not on this docs site.