Skip to main content
Glama
jstibal

Openterms-mcp

by jstibal
OverviewSchemaRelated ServersScoreDiscussions
Python

provider_activity

View receipt activity against your terms URL, including stats, unique agents, and recent receipts, using your provider API key.

Instructions

View receipt activity against your terms URL (requires provider API key via OPENTERMS_PROVIDER_KEY). Shows stats, unique agents, and recent receipts for your API.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMax receipts to return (default 10)

Implementation Reference

  • openterms_mcp_server.py:391-414 (handler)
    The handler function for provider_activity. Calls GET /v1/provider/stats with provider headers, returns stats including provider_id, verification status, receipt counts by period, unique agents, and action type breakdown.
    elif name == "provider_activity":
    if not PROVIDER_KEY:
        return "❌ OPENTERMS_PROVIDER_KEY not set. Register as a provider first."
    # Get stats
    resp = client.get("/v1/provider/stats", headers=_provider_headers())
    if resp.status_code != 200:
        return _format_error(resp)
    stats = resp.json()
    lines = [
        f"📊 Provider Activity",
        f"  Provider: {stats.get('provider_id', 'n/a')}",
        f"  Verified: {'✅' if stats.get('verified') else '❌'}",
        f"  Receipts (total): {stats.get('receipts_total', 0)}",
        f"  Receipts (24h): {stats.get('receipts_24h', 0)}",
        f"  Receipts (7d): {stats.get('receipts_7d', 0)}",
        f"  Receipts (30d): {stats.get('receipts_30d', 0)}",
        f"  Unique agents: {stats.get('unique_agents', 0)}",
    ]
    breakdown = stats.get('action_type_breakdown', {})
    if breakdown:
        lines.append("  Action types:")
        for atype, count in breakdown.items():
            lines.append(f"    {atype}: {count}")
    return "\n".join(lines)
  • openterms_mcp_server.py:135-147 (schema)
    The input schema for provider_activity, defined in the TOOLS list. It has an optional 'limit' integer parameter.
    {
    "name": "provider_activity",
    "description": (
        "View receipt activity against your terms URL (requires provider API key via OPENTERMS_PROVIDER_KEY). "
        "Shows stats, unique agents, and recent receipts for your API."
    ),
    "inputSchema": {
        "type": "object",
        "properties": {
            "limit": {"type": "integer", "description": "Max receipts to return (default 10)"},
        },
    },
},
  • openterms_mcp_server.py:21-148 (registration)
    Tool registration: provider_activity is registered in the TOOLS list (line 136). The MCP server exposes it via list_tools() which converts TOOLS into Tool objects, and call_tool() which routes to handle_tool('provider_activity', ...).
    TOOLS = [
    # --- MVP 1 Tools ---
    {
        "name": "issue_receipt",
        "description": (
            "Issue a cryptographically signed terms receipt BEFORE your agent takes an action. "
            "Returns an Ed25519-signed receipt proving consent to terms. "
            "If this returns POLICY_DENIED or POLICY_ESCALATION_REQUIRED, STOP and notify the user."
        ),
        "inputSchema": {
            "type": "object",
            "required": ["agent_id", "action_type", "terms_url", "terms_hash"],
            "properties": {
                "agent_id": {"type": "string", "description": "Identifier for this agent"},
                "action_type": {"type": "string", "enum": ["api_call", "data_access", "purchase", "custom"]},
                "terms_url": {"type": "string", "description": "URL of the terms being agreed to"},
                "terms_hash": {"type": "string", "description": "SHA-256 hash of the terms document (64 hex chars)"},
                "timestamp": {"type": "string", "description": "ISO 8601 timestamp (defaults to now)"},
                "pricing_version": {"type": "string", "description": "Pricing version (defaults to 2025-01)"},
                "action_context": {"type": "object", "description": "Optional metadata (provider, model, endpoint, etc.)"},
            },
        },
    },
    {
        "name": "verify_receipt",
        "description": "Verify a receipt's cryptographic integrity. Public — no API key needed.",
        "inputSchema": {
            "type": "object",
            "required": ["receipt_id", "canonical_hash", "signature", "key_id"],
            "properties": {
                "receipt_id": {"type": "string"},
                "canonical_hash": {"type": "string"},
                "signature": {"type": "string"},
                "key_id": {"type": "string"},
            },
        },
    },
    {
        "name": "check_balance",
        "description": "Check workspace USDC balance (minor units, 1 USDC = 1,000,000).",
        "inputSchema": {"type": "object", "properties": {}},
    },
    {
        "name": "get_pricing",
        "description": "Get current per-receipt pricing. Public — no API key needed.",
        "inputSchema": {"type": "object", "properties": {}},
    },
    {
        "name": "list_receipts",
        "description": "List recent receipts for this workspace.",
        "inputSchema": {
            "type": "object",
            "properties": {
                "limit": {"type": "integer", "description": "Max receipts to return (default 10, max 50)"},
                "action_type": {"type": "string", "description": "Filter by action type"},
            },
        },
    },
    # --- MVP 2: Policy Tools ---
    {
        "name": "get_policy",
        "description": (
            "Get the active policy (guardrails) for this workspace. "
            "Returns the rules that govern what this agent is allowed to do. "
            "An agent SHOULD call this on startup to understand its constraints."
        ),
        "inputSchema": {"type": "object", "properties": {}},
    },
    {
        "name": "simulate_policy",
        "description": (
            "Test whether a hypothetical action would be allowed by the current policy "
            "WITHOUT actually issuing a receipt. Use this to pre-check before acting."
        ),
        "inputSchema": {
            "type": "object",
            "required": ["action_type", "terms_url"],
            "properties": {
                "action_type": {"type": "string", "enum": ["api_call", "data_access", "purchase", "custom"]},
                "terms_url": {"type": "string", "description": "URL of the terms"},
                "action_context": {"type": "object", "description": "Optional context metadata"},
            },
        },
    },
    {
        "name": "policy_decisions",
        "description": (
            "View recent policy evaluation decisions (allow/deny/escalate) for this workspace. "
            "Useful for auditing and understanding what the policy engine has been doing."
        ),
        "inputSchema": {
            "type": "object",
            "properties": {
                "limit": {"type": "integer", "description": "Max decisions to return (default 10)"},
                "decision": {"type": "string", "enum": ["allow", "deny", "escalate"], "description": "Filter by decision type"},
            },
        },
    },
    # --- MVP 3: Provider Verification Tools ---
    {
        "name": "verify_receipt_by_hash",
        "description": (
            "Verify a receipt by its canonical hash. Public — no API key needed. "
            "Use this to check if an agent has a valid consent receipt before serving a request. "
            "Returns receipt details and cryptographic verification result."
        ),
        "inputSchema": {
            "type": "object",
            "required": ["canonical_hash"],
            "properties": {
                "canonical_hash": {"type": "string", "description": "The canonical hash of the receipt to verify"},
            },
        },
    },
    {
        "name": "provider_activity",
        "description": (
            "View receipt activity against your terms URL (requires provider API key via OPENTERMS_PROVIDER_KEY). "
            "Shows stats, unique agents, and recent receipts for your API."
        ),
        "inputSchema": {
            "type": "object",
            "properties": {
                "limit": {"type": "integer", "description": "Max receipts to return (default 10)"},
            },
        },
    },
]
  • openterms_mcp_server.py:158-162 (helper)
    Helper function that builds HTTP headers with the provider API key (OPENTERMS_PROVIDER_KEY) for authenticating provider-specific API calls like provider_activity.
    def _provider_headers():
    h = {"Content-Type": "application/json"}
    if PROVIDER_KEY:
        h["Authorization"] = f"Bearer {PROVIDER_KEY}"
    return h

Tool Definition Quality

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description implies a read-only operation ('View'), mentions authentication requirements, and describes what is returned (stats, unique agents, receipts). However, it does not explicitly state non-destructiveness or other behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the purpose and authentication requirement, followed by what is shown. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one optional parameter and no output schema, the description adequately explains the action and output. It misses some detail about the exact structure of 'stats' or 'unique agents', but is sufficient for selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with one parameter (limit) having a description. The description adds no additional meaning to the parameter beyond what the schema provides, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the verb 'View' with a specific resource 'receipt activity against your terms URL', clearly distinguishing it from siblings like list_receipts or verify_receipt by specifying it's for the provider's own API and shows stats, unique agents, and recent receipts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states the prerequisite (requires provider API key via OPENTERMS_PROVIDER_KEY) but does not explicitly guide when to use this tool versus siblings like list_receipts or check_balance. Context is implied but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jstibal/openterms-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server