Skip to main content
Glama
revenium

Revenium MCP Server

Official
by revenium
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

PyPI version Python Versions Documentation License: MIT MCP 2025-06-18

Revenium MCP Server

Connect AI agents to Revenium for cost tracking, alerting, and usage-based billing

Once you've connected your AI applications to Revenium using any of the supported middleware libraries or via direct API integration, this MCP server allows agents to directly interact with your Revenium account. Connect Claude, OpenAI, or any MCP-compatible AI assistant to Revenium to configure AI cost alerts & tracking as well as usage-based billing for AI products.

Features

AI Cost Tracking & Alerting - Never Be Surprised by Unexpected AI Costs Again

  • Ask AI agents to set up AI cost alerts to avoid unexpected costs

  • Ask AI agents to track their own costs with Revenium as they carry out actions within your application

  • Ask Revenium to calculate AI cost & usage trends over time and set up alerts to immediately send slack or email notifications when anomalies occur

  • Quickly investigate the reasons for AI cost spikes. Identify abnormal changes in spending by agent, API key, product, customer, and more.

  • Use AI agents to integrate Revenium metering into your applications if not using Revenium's pre-built SDKs

Outcomes for AI - Track AI Agent Job ROI

  • Track AI agent job execution, measure ROI, and report outcomes

  • Analyze conversion funnels from job initiation through outcome delivery

  • Report business outcomes tied to specific AI agent jobs

Tool Registry - Register & Price Your AI Tools

  • Register, manage, and analyze AI tools with built-in pricing tiers

  • Support for multiple pricing models: per-call, per-token, tiered, flat, and subscription

  • Track tool usage events and analyze cost, latency, and success rates

Usage-based Billing & Chargebacks (Optional)

If or when you're ready to turn AI costs into AI revenue, the Revenium MCP will be there to help quickly make the transition.

  • Ask your agent to manage all elements of usage-based billing & cost chargebacks

  • Use agents to manage products, customers, subscriptions, and subscriber credentials

Profile-Based Tool Selection

The MCP provides the appropriate tools for each use case depending on your chosen startup profile:

  • Starter Profile (7 tools): Cost monitoring, alerts, analytics, AI metering integration

  • Business Profile (20 tools): All Starter tools plus product management, customer management, subscriptions, billing, tool registry, AI insights, AI agents and cost controls

Related MCP server: Pulse MCP Server

Getting Started

Connect to the Hosted Server (Recommended — Nothing to Install)

Revenium hosts the MCP server at https://mcp.revenium.ai/mcp. Authentication is an OAuth sign-in in your browser — no API key to copy and no local process to manage.

Claude Code:

claude mcp add --transport http revenium https://mcp.revenium.ai/mcp

Then run /mcp inside Claude Code and choose Authenticate to complete the browser sign-in.

claude.ai (web & desktop): Settings → Connectors → Add custom connector → paste https://mcp.revenium.ai/mcp.

Cursor and other MCP clients with remote-server support:

{
  "mcpServers": {
    "revenium": { "url": "https://mcp.revenium.ai/mcp" }
  }
}

Some clients declare the transport explicitly — if yours does, set its type/transport field to HTTP (for example "type": "http" in VS Code).

Clients that only speak stdio can bridge with mcp-remote:

npx mcp-remote https://mcp.revenium.ai/mcp

Prefer to run the server yourself? Use any of the local options below.

For Claude Code Users (Local Install)

  1. Install uv:

    pip install uv

  2. Add to Claude Code:

    claude mcp add revenium \
  -e REVENIUM_API_KEY=hak_your_api_key_here \
  -- uvx revenium-mcp

Done! Claude Code will manage the configuration.

For Local Development/Testing

  1. Install uv:

    pip install uv

  2. Create .env file:

    cat > .env << EOF
REVENIUM_API_KEY=hak_your_api_key_here
TOOL_PROFILE=starter
EOF

  3. Run the server:

    uvx revenium-mcp

See Installation for Cursor, Augment, and other integrations.

For Containerized Deployment

Build and run the MCP server in a container. Useful for hosted HTTP deployments and CI integration. Clone this repository first, then from the repo root:

docker build -t revenium-mcp .
docker run -d --name revenium-mcp \
  -p 8000:8000 \
  -e AUTH_MODE=api_key \
  -e REVENIUM_BASE_URL=https://api.revenium.ai \
  -e MCP_SERVER_BASE_URL=https://mcp.your-domain.com \
  revenium-mcp

In api_key mode there is no server-wide REVENIUM_API_KEY — each caller authenticates with their own Revenium key (rev_sk_ write or rev_rk_ read), sent as an Authorization: Bearer header and validated per request against the platform.

Defaults baked into the image:

  • TRANSPORT_MODE=http (stdio doesn't make sense in a container)

  • MCP_HOST=0.0.0.0 (binds all interfaces inside the container)

  • MCP_PORT=8000

The container runs as a non-root user (mcp, UID 1000). Health probes:

  • GET /health — liveness, always returns 200 (no external calls)

  • GET /ready — readiness, returns 200 when the Revenium API is reachable with the configured key (503 otherwise)

For Full HTTPS Stack via docker compose

Local multi-tenant deployment with Caddy doing TLS termination.

cp .env.example .env
# Edit .env — set AUTH_MODE=api_key, REVENIUM_BASE_URL=https://api.revenium.ai,
# and MCP_SERVER_BASE_URL=https://localhost:8443
docker compose up --build

Endpoints:

  • https://localhost:8443/mcp — the MCP protocol endpoint

  • https://localhost:8443/health — liveness, no auth

  • https://localhost:8443/ready — readiness, no auth

First-time TLS: Caddy generates a self-signed cert via its internal CA. Browsers will warn "untrusted certificate". The cert is cryptographically valid — accept the warning for local dev. If you need the cert trusted system-wide, extract the root CA from the caddy_data volume and add it to your OS trust store using the OS-specific procedure (out of scope for this README).

The cert persists in the caddy_data volume between runs.

To stop:

docker compose down

To wipe state (including the cert):

docker compose down -v

Connecting a client to the local compose stack

Once the compose stack is running, point any MCP client that supports remote HTTP servers at the endpoint and send your Revenium key as a bearer token (for a hosted deployment, replace https://localhost:8443 with your server's public URL):

{
  "mcpServers": {
    "revenium": {
      "url": "https://localhost:8443/mcp",
      "headers": {
        "Authorization": "Bearer rev_sk_your_key_here"
      }
    }
  }
}

Clients that only speak stdio can use the mcp-remote shim.

TLS note for Node-based clients (including mcp-remote): Caddy signs localhost with its internal CA, which Node.js does not trust by default. Export the root CA from the caddy_data volume and pass it via NODE_EXTRA_CA_CERTS=/path/to/caddy-root.crt, or — for a quick local-only workaround, never in production — set NODE_TLS_REJECT_UNAUTHORIZED=0. See the "First-time TLS" note above for the browser equivalent.

MCP Specification

Implements Model Context Protocol revision 2026-07-28 — the LATEST_PROTOCOL_VERSION of the pinned mcp SDK, which is what the server negotiates. Earlier revisions (including 2025-11-25 and 2025-06-18) are still served to older clients.

  • Framework: FastMCP (pinned to fastmcp==4.0.0)

  • Transport: stdio (default) and HTTP (set TRANSPORT_MODE=http)

  • Protocol: JSON-RPC 2.0

Requirements

Prerequisites

  • Python 3.11+ with pip

  • Your Revenium API key (get one at ai.revenium.io)

  • Optional: uv/uvx for easier installation

System Requirements

  • Operating System: macOS, Linux, Windows (with WSL)

  • Network: Internet connection for API communication

  • MCP Client: Claude Code, Cursor, Augment IDE, or any MCP-compatible client

What Gets Tracked

When you use this MCP server, the following data flows between your AI assistant and Revenium:

Data Sent to Revenium

  • API requests for cost analytics and queries

  • Alert configuration requests (thresholds, notifications)

  • Customer/product management operations (when using Business profile)

  • Transaction lookup queries

Data Retrieved from Revenium

  • AI usage metrics and costs (grouped by provider, model, customer, etc.)

  • Alert status and notification configurations

  • Product/subscription information (Business profile)

  • Analytics data and cost trends

  • Anomaly detection results

Data NOT Collected

  • ❌ Your AI assistant's conversations or prompts

  • ❌ Prompt content (unless you explicitly submit transactions for metering)

  • ❌ Personal data beyond what you configure in Revenium

  • ❌ File contents or local data

Privacy & Security

  • All communication uses your Revenium API key for authentication

  • Data is transmitted securely over HTTPS

  • API keys are never logged or exposed in tool responses

  • Data handling is subject to Revenium's privacy policy

Environment Configuration

The MCP server uses environment variables for configuration. The method you use depends on your setup:

Setup

Method

When to Use

Claude Code

-e flag in claude mcp add

Integrating with Claude Code (most common)

Cursor/Augment

JSON config "env": {...}

Integrating with Cursor or Augment IDE

Local testing

.env file

Testing the server directly from command line

Important: Don't mix methods. Choose the one that matches your use case:

  • If using Claude Code, you only need the -e flag (no .env file or export needed)

  • If testing locally, use a .env file (no export needed)

  • Never use export - it's session-specific and gets lost when you close the terminal

Installation

No install needed for most users: the hosted server at https://mcp.revenium.ai/mcp works with any remote-capable MCP client — see Connect to the Hosted Server. The steps below are for running the server locally.

Install Python Package

Option 1: Installation with uvx (Recommended for local testing)

# Install uv if you don't have it
pip install uv

# Create .env file
cat > .env << EOF
REVENIUM_API_KEY=hak_your_api_key_here
TOOL_PROFILE=starter
EOF

# Run the server (automatically loads .env)
uvx revenium-mcp

Option 2: Package Installation in Virtual Environment

# Create and activate virtual environment
python -m venv revenium-mcp-env
source revenium-mcp-env/bin/activate  # On Windows: revenium-mcp-env\Scripts\activate

# Install package
pip install revenium-mcp

# Create .env file for configuration
cat > .env << EOF
REVENIUM_API_KEY=hak_your_api_key_here
TOOL_PROFILE=starter
EOF

# Run the server (automatically loads .env from current directory)
python -m revenium_mcp_server

Note: The .env file should be in the directory where you run the server. Never commit .env to version control.

Choose Your Profile & Start the Server

The MCP server supports two profiles to match your use case:

Profile

Tools

Target Users

Use Cases

Starter (default)

7 tools

Cost monitoring & alerts

Cost analysis, AI transaction metering

Business

20 tools

Full platform

Product & subscription management, usage-based billing, comprehensive analytics, tool registry, AI insights, AI agents, cost controls

The server uses the Starter profile by default. To use the Business profile, set the TOOL_PROFILE environment variable:

With uvx and .env file:

# Starter Profile (7 tools) - Cost monitoring, alerts, AI metering integration (default)
cat > .env << EOF
REVENIUM_API_KEY=hak_your_api_key_here
TOOL_PROFILE=starter
EOF
uvx revenium-mcp

# Business Profile (20 tools) - Usage-based billing & AI Analytics
cat > .env << EOF
REVENIUM_API_KEY=hak_your_api_key_here
TOOL_PROFILE=business
EOF
uvx revenium-mcp

For Claude Code

Choose one of the following integration methods. Both use the Starter profile by default. To use the Business profile, add -e TOOL_PROFILE=business to the command:

Option 1: Installation with uvx

# Install uv if you don't have it
pip install uv

# Starter profile (default)
claude mcp add revenium \
  -e REVENIUM_API_KEY=hak_your_api_key_here \
  -- uvx revenium-mcp

# Business profile (for advanced features)
claude mcp add revenium \
  -e REVENIUM_API_KEY=hak_your_api_key_here \
  -e TOOL_PROFILE=business \
  -- uvx revenium-mcp

Option 2: Installation with python virtual environment

# Create and activate virtual environment
python -m venv revenium-mcp-env
source revenium-mcp-env/bin/activate  # On Windows: revenium-mcp-env\Scripts\activate

# Install package
pip install revenium-mcp

# Add to Claude Code using venv python (starter profile - default)
claude mcp add revenium \
  -e REVENIUM_API_KEY=hak_your_api_key_here \
  -- ./revenium-mcp-env/bin/python -m revenium_mcp

# For business profile, add the environment variable:
claude mcp add revenium \
  -e REVENIUM_API_KEY=hak_your_api_key_here \
  -e TOOL_PROFILE=business \
  -- ./revenium-mcp-env/bin/python -m revenium_mcp

Claude Code Slash Commands

Optional prompt shortcuts for Claude Code users. Copy the slash commands to your project's .claude/commands/ folder.

Command

Description

/rm-summary-1h

Spending summary (last hour)

/rm-summary-24h

Spending summary (last 24 hours)

/rm-summary-7d

Spending summary (last 7 days)

/rm-summary-30d

Spending summary (last 30 days)

/rm-anomalies-24h [threshold]

Detect cost anomalies (24h, default $50)

/rm-anomalies-7d [threshold]

Detect cost anomalies (7d, default $50)

/rm-anomalies-30d [threshold]

Detect cost anomalies (30d, default $50)

/rm-alert-budget-daily [threshold]

Create daily budget alert (default $100)

/rm-alert-per-transaction [threshold]

Create per-transaction alert (default $5)

/rm-customers-30d

Top customers by cost (30 days)

For Cursor / Augment IDE (or any IDE allowing MCP JSON import)

Install uv:

pip install uv

Configure MCP server:

  1. Open Cursor/Augment settings (Ctrl/Cmd + ,) | (Cmd + Shift + P for Augment)

  2. Navigate to Extensions → MCP or create ~/.cursor/mcp.json | for Augment, import JSON below into MCP settings

  3. Add server configuration:

Standard Configuration:

{
  "mcpServers": {
    "revenium": {
      "command": "uvx",
      "args": ["revenium-mcp"],
      "env": {
        "REVENIUM_API_KEY": "hak_your_api_key_here"
      }
    }
  }
}

Basic Usage

After installation, the MCP server provides tools to your AI assistant. Simply ask natural language questions:

Cost Monitoring Examples

"Summarize my AI costs for the last month"
"Show me a breakdown of costs by provider"
"Alert me when monthly costs for Anthropic exceed $500"
"Why did my costs spike yesterday?"

Slack Integration Examples

"Set up Slack notifications for cost alerts"
"Send all cost alerts to #ai-spending channel"
"Create a spike detection alert that notifies my team on Slack"

Analytics Examples

"Analyze cost anomalies in the last 7 days"
"Find API key anomalies using aggressive sensitivity"
"Show me cost trends for the last month"
"Detect what caused my cost increase yesterday"

AI Metering Integration

"Get Python integration guide for AI transaction metering"
"Help me integrate this Python AI function with Revenium"
"Generate test transaction data and verify it's processing correctly"

See AI Cost Analytics & Alerting Tools for complete tool descriptions.

Advanced Usage

The MCP server provides different tool sets based on your selected profile:

Alert Management

Set up intelligent monitoring for costs, usage, and performance metrics.

  • Create budget threshold and spike detection alerts

  • Get notified via Slack or email when patterns change

  • Example: "Alert me when monthly costs for Anthropic exceed $500"

  • Example: "Create a spike detection alert when token use exceeds 1,500,000 tokens per hour"

  • Example: "Alert when my error rate exceeds 5% every 5 minutes"

  • Example: "Set up cost per transaction monitoring so any single AI call costing more than $1.50 triggers an immediate Slack alert"

Relative Change Alerts (Trend Detection)

Detect percentage-based cost changes over configurable time periods. Use RELATIVE_CHANGE alerts with INCREASES_BY or DECREASES_BY operators to catch trends before they become problems.

Setting

Options

Operators

INCREASES_BY, DECREASES_BY

Periods

DAILY, WEEKLY, MONTHLY, QUARTERLY

"Alert me if weekly AI costs increase by more than 25%"
"Create a relative change alert that triggers when monthly spend decreases by 15%"
"Set up a daily trend alert — notify me on Slack if costs increase by 10% day over day"

Slack Integration

  • Example: "Set up a Slack notification channel for Revenium alerts"

  • Example: "Add a new slack channel for all customer spending alerts"

  • Example: "Send all product spending anomalies to the Slack channel #product-spend-alerts."

AI Business Analytics

Analyze costs, usage patterns, and performance.

  • Cost trend analysis and breakdowns

  • Example: "Summarize my costs for the last day/week/month and highlight any anomalies"

  • Example: "Explain why costs grew last week"

  • Example: "Show me a breakdown of AI costs last month by provider/customer/product/agent"

Common Use Cases

"Why did my costs spike yesterday?"

  • "Analyze cost anomalies in the last 7 days focusing on abnormal spending by model or API key"

  • "Detect what caused my cost increase yesterday. Only focus on anomalies larger than $20 vs. the norm"

"Find anomalies across all dimensions"

  • "Show me cost anomalies in the last month across all providers, models, agents, API keys, and customers"

  • "Analyze all dimensions for cost spikes above $150 in the past 30 days"

"Detect small but significant anomalies to identify early changes in behavior before they become large issues"

  • "Find API key anomalies in the last week using aggressive sensitivity"

AI Metering Management

Track AI usage, token consumption, and transaction data with comprehensive integration guidance.

  • Get assistance creating a new custom integration from your AI agents to Revenium

  • Get comprehensive implementation guidance with working code examples for Python and JavaScript

  • Submit AI transaction data and verify successful processing

  • Example: "Get Python integration guide with working code examples for AI transaction metering"

  • Example: "Get JavaScript integration guide with Revenium documentation"

  • Example: "Check the status of transaction tx_12345"

  • Example: "Help me integrate this python AI function with Revenium's AI metering API"

  • Example: "Generate test transaction data from our application and ensure all metadata is properly mapped in Revenium."

Jobs & Outcomes (Outcomes for AI)

Track AI agent job execution, measure ROI, and report business outcomes. Jobs represent units of AI agent work; outcomes capture the business value delivered.

Key actions:

  • list_jobs — List jobs with filtering and pagination

  • get_job — Retrieve a specific job by its agenticJobId

  • get_job_transactions — View transactions associated with a job

  • get_job_roi — Calculate return on investment for a job

  • get_job_types — List available job type classifications

  • get_conversion_funnel — Analyze conversion from job initiation through outcome

  • report_outcome — Report a business outcome tied to a job

Note: When referencing jobs, use the agenticJobId field as the job_id parameter.

"List all AI agent jobs from the last 7 days"
"Show me the ROI for job aj_abc123"
"Report a successful outcome for job aj_xyz789 with revenue of $150"
"Show the conversion funnel for jobs this month"

Usage-Based Billing Tools (Business Profile Only)

Product Management

Create and manage your AI products, pricing tiers, and billing models.

  • Design usage-based or subscription pricing

  • Design chargeback models so that all AI spending is invoiced to the correct internal department

  • Set up free tiers and graduated pricing for SaaS products

  • Example: "Create a Gold Tier AI product with $199 per month base fee plus usage-based pricing that charges 1.10x the actual AI costs"

  • Example: "Create a new product called 'Smart Analytics' with usage-based pricing"

  • Example: "Set up a free tier with 1000 API calls, then charge a 25% premium on my AI costs for every call"

  • Example: "Show me the number of subscribers for each of my products"

Customer Management

Handle customer relationships, organizations, and user hierarchies.

  • Manage customer or internal organizations used for cost attribution

  • Create & manage subscribers (internal or external)

  • Track customer usage

  • Example: "List all organizations and their subscription status"

Subscription Management

Control customer subscriptions, billing cycles, and plan changes.

  • Create and modify customer subscriptions

  • Track subscription analytics

  • Example: "Create a monthly subscription for customer ABC Corp to the product 'analytics-suite'"

  • Example: "Show me all active subscriptions to the AI Analytics product"

  • Example: "List subscriptions that are about to expire this month"

Tool Registry Management

Register, manage, and analyze AI tools in the Revenium Tool Registry with pricing tiers, event metering, and analytics.

Key actions:

  • list — List registered tools with pagination

  • get — Retrieve a specific tool by ID

  • create — Register a new tool with full configuration including pricing

  • create_simple — Quick tool registration with sensible defaults

  • update — Update a tool's configuration

  • delete — Remove a tool from the registry

  • search — Search tools by name, type, or other criteria

  • meter_event — Submit a tool/function call for metering

  • list_events — List tool event logs (filterable)

  • analytics — Get usage analytics across tools

Pricing models: per_request, tiered, flat

"Register a new tool called 'sentiment-analyzer' with per_call pricing at $0.02 per call"
"Create a tool 'doc-summarizer' with tiered pricing — free up to 100 calls, then $0.01 each"
"List all registered tools in the tool registry"
"Show me tool analytics for the last 30 days"
"Search for tools related to 'translation'"

Configuration Options

Required Configuration

Variable

Required

Description

Example

REVENIUM_API_KEY

✅

Your account API key from the API Keys page in Revenium

hak_1234567890abcdef

Automatically Loaded Values

These values are loaded from your account and can be overridden if needed:

Variable

Override When

Example

REVENIUM_TEAM_ID

Multi-tenant environments

ABC123x

REVENIUM_TENANT_ID

Operating on behalf of different tenant

DEF456n

REVENIUM_OWNER_ID

Non-primary user scenarios

GHI789z

REVENIUM_DEFAULT_EMAIL

Custom alert email preferences

alerts@company.com

Optional Configuration

Variable

Required

Description

Example

REVENIUM_BASE_URL

API endpoint URL (defaults to main Revenium instance)

https://api.revenium.ai

REVENIUM_APP_BASE_URL

Revenium application/analytics host used by tool-cost analytics (/api/v2/analytics/*) and by the application links the Slack setup actions hand you. Known non-production environments are paired with REVENIUM_BASE_URL automatically; set this only for an environment the server does not recognise, otherwise it falls back to production and 401s for non-prod API keys.

https://ai.dev.hcapp.io

LOG_LEVEL

Logging verbosity level

DEBUG

REQUEST_TIMEOUT

API request timeout in seconds

30

Overriding Default Values in IDE / MCP Client (Advanced Use Cases)

You can override the automatically loaded values if needed:

When you might need overrides:

  • Multi-tenant environments: Switching organizations in a multi-tenant Revenium installation

  • Custom email preferences: Change default email address for alert configuration

  • Custom API endpoints: When not using Revenium's default API endpoints

Troubleshooting

Authentication Errors

  • Verify your API key is correct and active

  • Use the diagnostic tool to check configuration status

  • Ensure the base URL is correct for your environment

  • Check that the /users/me endpoint is accessible with your API key

Configuration Priority

The system loads configuration values in this priority order:

  1. MCP client JSON configuration env section (highest priority)

  2. System environment variables

  3. Automatically loaded values from Revenium's API

Use the system_diagnostics tool to see exactly which values are being used from each source.

Common Issues

Issue: MCP server not appearing in AI assistant Solution: Verify installation with uvx revenium-mcp --version and check MCP client configuration

Issue: Authentication errors Solution: Verify API key based on your setup:

For local development (.env file):

# Check if .env exists and contains your key
cat .env | grep REVENIUM_API_KEY

# Verify the server can load it (run from project directory)
python -c "import os; from dotenv import load_dotenv; load_dotenv(); print('API Key:', os.getenv('REVENIUM_API_KEY', 'NOT FOUND')[:20] + '...')"

For Claude Code:

claude mcp list  # Verify configuration includes API key

For Cursor/Augment: Check your MCP JSON config file includes REVENIUM_API_KEY in the env section.

For any setup: Use the system_diagnostics tool to see exactly which configuration values are being used.

Issue: Tools not working as expected Solution: Check you're using the correct profile (Starter vs Business) for your use case

Documentation

For detailed documentation, visit docs.revenium.io

Additional resources:

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

  • Reporting bugs

  • Suggesting enhancements

  • Submitting pull requests

  • Development workflow

Code of Conduct

This project adheres to a Code of Conduct to ensure a welcoming and inclusive community. See CODE_OF_CONDUCT.md for details.

Security

Security is a top priority. For security concerns, please see SECURITY.md for:

  • Our security policy

  • How to report vulnerabilities

  • Security best practices

License

This project is licensed under the MIT License. See LICENSE for full details.

Support

For questions, issues, or feature requests:

Development

Local Development Setup

# Clone repository
git clone https://github.com/revenium/revenium-mcp.git
cd revenium-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies (including dev dependencies)
pip install -e ".[dev]"

# Create .env file for development
cat > .env << EOF
REVENIUM_API_KEY=hak_your_api_key_here
REVENIUM_TEAM_ID=your_team_id
LOG_LEVEL=DEBUG
EOF

# Verify .env is loaded
python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(f'API Key loaded: {os.getenv(\"REVENIUM_API_KEY\", \"NOT FOUND\")[:20]}...')"

# Run tests
pytest

# Run linters
black .
isort .
mypy .
flake8

Important: Never commit your .env file. The repository includes .env.example as a template.

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=revenium_mcp_server --cov-report=html

# Run specific test file
pytest tests/test_auth.py

Contributing

See CONTRIBUTING.md for detailed development guidelines including:

  • Code style requirements

  • Testing requirements

  • Pull request process

  • Release process

Acknowledgments

Built by the Revenium team with contributions from the community.

Special thanks to:

  • Anthropic for the Model Context Protocol specification

  • The open-source community for MCP tooling and support

Available Tools

7 tools
business_analytics_managementC

Business analytics and cost analysis with enhanced statistical anomaly detection and new entity detection. Key actions: get_provider_costs, get_model_costs, get_customer_costs, get_api_key_costs, get_agent_costs, get_user_costs, get_tool_costs, get_top_tools, get_tool_costs_by_agent, get_tool_costs_by_provider, get_cost_summary, analyze_cost_anomalies. For anomaly detection use: min_impact_threshold, include_dimensions. For new entity detection use: detect_new_entities, min_new_entity_threshold. Use get_examples() for parameter guidance and get_capabilities() for status.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNoget_capabilities
breakdown_byNo
periodNo
groupNo
filtersNo
pageNo
sizeNo
thresholdNo
min_impact_thresholdNo
include_dimensionsNo
sensitivityNo
dry_runNo
example_typeNo
detect_new_entitiesNo
min_new_entity_thresholdNo

TDQS

C2.6/5.0
Behavior2/5

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

No annotations provided, and the description does not disclose behavioral traits such as side effects, authentication requirements, rate limits, or data modification potential. The phrase 'enhanced statistical anomaly detection' hints at analysis but lacks detail.

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

Conciseness3/5

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

The description is moderately concise but includes a long list of actions that could be streamlined. It front-loads the general purpose but adds redundant specifics, making it longer than necessary.

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

Completeness2/5

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

Without annotations or output schema, and with 15 parameters, the description fails to provide a complete picture. It does not explain what actions do, how parameters affect results, or return values, leaving gaps for an agent to use the tool correctly.

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

Parameters2/5

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

Schema coverage is 0%, so the description must compensate. It explains a few parameters (min_impact_threshold, include_dimensions, detect_new_entities, min_new_entity_threshold) but leaves most of the 15 parameters unexplained, providing insufficient guidance for correct invocation.

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

Purpose4/5

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

The description states 'Business analytics and cost analysis with enhanced statistical anomaly detection and new entity detection,' giving a clear general purpose. However, it does not differentiate this tool from sibling tools like manage_alerts or manage_metering, reducing clarity.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus its siblings. The description only refers to internal sub-actions (get_examples, get_capabilities) without contextualizing when the tool is appropriate.

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

manage_alertsB

AI spending alerts and anomaly monitoring with three alert types: (1) Spike Detection - create_threshold_alert for real-time monitoring, (2) Budget Threshold - create_cumulative_usage_alert for period tracking, (3) Relative Change - create with alertType RELATIVE_CHANGE and INCREASES_BY/DECREASES_BY operators for trend detection. Supports persistence-based triggering with triggerAfterPersistsDuration. Use get_examples() for comprehensive usage guidance.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYes
alert_idNo
nameNo
metricNo
thresholdNo
periodNo
period_minutesNo
emailNo
slack_config_idNo
triggerAfterPersistsDurationNo
periodDurationNo
filtersNo
pageNo
sizeNo
dry_runNo
confirmNo
alert_typeNo
textNo
queryNo
resource_typeNoanomalies
anomaly_idNo
anomaly_idsNo
anomaly_dataNo
descriptionNo
tagsNo
enabledNo
alertTypeNo
metricTypeNo
slackConfigurationsNo
notificationAddressesNo

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description must carry the full burden. It focuses on creation patterns but does not disclose side effects, permissions, rate limits, or other behavioral traits. The tool likely supports CRUD operations, but the description only mentions creation.

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

Conciseness4/5

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

The description is concise with three sentences, front-loading the purpose and using numbered lists for clarity. No wasted words, though the reference to get_examples() is a minor inefficiency.

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

Completeness2/5

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

Given the tool's complexity (30 parameters, no output schema, no annotations), the description is incomplete. It only covers creation aspects, ignoring other likely actions like listing, updating, or deleting alerts. Many parameters remain unexplained.

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 0%, so description must compensate. It explains key parameters like action values (create_threshold_alert, etc.), alertType, triggerAfterPersistsDuration. However, many parameters (e.g., filters, page, size, email) are not addressed, leaving gaps.

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

Purpose4/5

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

The description clearly states it manages AI spending alerts and anomaly monitoring, listing three alert types with specific creation methods. However, it does not differentiate from sibling tools like business_analytics_management or manage_metering.

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 provides guidance on when to use each alert type (spike detection, budget threshold, relative change) and references get_examples() for more help. It does not mention when not to use this tool or compare with alternatives.

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

manage_meteringC

Submit AI transaction metering metadata and lookup existing AI transactions metered by Revenium. Receive guidance for writing new integrations to Revenium's AI metering API using python and typescript. Key actions: submit_ai_transaction, lookup_transactions (requires transaction IDs), lookup_recent_transactions (browse without IDs), get_integration_guide, list_ai_models, validate. Supports Python and JavaScript integration examples. Use get_capabilities() for full guidance.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNoget_capabilities
modelNo
providerNo
input_tokensNo
output_tokensNo
duration_msNo
organization_idNo
subscription_idNo
product_idNo
pageNo
sizeNo
queryNo
dry_runNo
example_typeNo
languageNo
use_caseNo
textNo
descriptionNo
transaction_idNo
transaction_idsNo
wait_secondsNo
return_transaction_dataNo
max_retriesNo
retry_intervalNo
search_page_rangeNo
page_sizeNo
early_terminationNo
subscriberNo
trace_idNo
task_typeNo
agentNo
is_streamedNo
response_quality_scoreNo
stop_reasonNo
time_to_first_tokenNo

TDQS

C2.7/5.0
Behavior2/5

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

No annotations exist, and the description fails to disclose behaviors like idempotency, error handling, or side effects. It mentions integration guides but not operational traits.

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

Conciseness3/5

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

The description is moderately concise but includes a potential inconsistency (python/typescript vs. Python/JavaScript) and redundant enumeration of actions.

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

Completeness2/5

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

With 35 undocumented parameters, no output schema, and no annotations, the description is insufficient for an agent to invoke the tool correctly. It relies on get_capabilities() for full guidance.

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

Parameters1/5

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

Schema coverage is 0%, and the description provides no explanation of any of the 35 parameters. It only mentions high-level actions, leaving parameter usage completely unspecified.

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

Purpose4/5

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

The description clearly states it submits and looks up AI transaction metering metadata, listing key actions. It distinguishes from siblings by focusing on AI metering, but the name 'manage_metering' is vague.

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?

It provides some guidance for specific actions (e.g., lookup_transactions requires IDs, lookup_recent_transactions browses without), but lacks when-not-to-use or alternatives relative to sibling tools.

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

slack_managementC

Unified Slack integration management combining configuration, OAuth workflow, and setup assistance. Key actions: list_configurations, get_configuration, set_default_configuration, initiate_oauth, guided_setup, quick_setup. Use get_capabilities() for complete action list.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNoget_capabilities
config_idNo
pageNo
sizeNo
return_toNo
dry_runNo
skip_promptsNo

TDQS

C2.4/5.0
Behavior2/5

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

No annotations exist, so the description must disclose behavioral traits. It mentions combining configuration, OAuth, and setup, but does not specify side effects, permissions, or whether actions are read-only or destructive. The agent lacks crucial behavioral context.

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

Conciseness3/5

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

The description is short (two sentences) and lists actions, but lacks front-loading of critical information. It is not verbose, but the structure could be improved by highlighting the action parameter's role first.

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

Completeness1/5

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

Given the complexity (7 parameters, no output schema, no parameter descriptions), the description is severely incomplete. It fails to explain how actions map to parameters, return values, or expected behavior, leaving the agent with insufficient information to use the tool correctly.

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

Parameters1/5

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

Schema description coverage is 0%, and the description adds no meaning to any of the 7 parameters. Parameters like config_id, return_to, dry_run, and skip_prompts are completely unexplained, forcing the agent to guess.

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

Purpose4/5

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

The description states it is a 'Unified Slack integration management' and lists key actions like list_configurations, OAuth, and setup. This gives a clear purpose, though it does not strongly differentiate from sibling tools like system_setup or tool_introspection.

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

Usage Guidelines2/5

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

The only usage guidance is 'Use get_capabilities() for complete action list', which implies a starting point. No explicit when-to-use, when-not-to-use, or comparison with alternatives is provided.

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

system_diagnosticsC

Unified system diagnostics combining configuration analysis, auto-discovery debugging, and log analysis. Key actions: environment_variables, debug, get_internal_logs, analyze_operations. Use get_capabilities() for complete action list.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNosystem_health
format_outputNo
include_recommendationsNo
include_sensitiveNo
show_detailed_analysisNo
log_typeNo
operation_filterNo
pageNo
sizeNo
pagesNo
search_all_pagesNo
search_termNo
status_filterNo

TDQS

C2.4/5.0
Behavior2/5

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

With no annotations provided, the description must disclose behavioral traits but only mentions 'diagnostics' without stating whether the tool is read-only, destructive, or has side effects. No mention of authentication requirements, rate limits, or data handling.

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

Conciseness4/5

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

The description is concise, using two sentences to convey purpose and a pointer to more details. However, it could be better structured by grouping related information (e.g., separating purpose from parameter guidance).

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

Completeness1/5

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

For a tool with 13 parameters, no output schema, and no annotations, the description is severely incomplete. It fails to explain return values, parameter usage, or any constraints, making it nearly impossible for an AI agent to invoke correctly without additional context.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not explain any of the 13 parameters. Keywords like environment_variables are listed but not linked to the input schema, leaving the AI agent with no understanding of how to set parameters like action, format_output, or search_term.

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

Purpose4/5

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

The description clearly states this tool is for unified system diagnostics, combining configuration analysis, auto-discovery debugging, and log analysis. It lists key actions and points to get_capabilities for a complete list, but doesn't specify the output format or what the tool returns, preventing a perfect score.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus siblings like business_analytics_management or slack_management. The only hint is 'Use get_capabilities() for complete action list,' but no context on prerequisites or scenarios where this tool is appropriate.

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

system_setupC

Unified system setup and onboarding combining welcome guidance, setup checklist, and email verification. Key actions: show_welcome, setup_checklist, check_status, validate_email. Use get_capabilities() for complete action list.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNoshow_welcome
show_environmentNo
include_recommendationsNo
confirm_completionNo
emailNo
validate_formatNo
suggest_smart_defaultsNo
include_setup_guidanceNo
test_configurationNo

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description must fully disclose behavior. It lists actions like show_welcome and validate_email, but does not mention side effects, permissions, or state changes (e.g., whether email validation is persistent). The behavior is partially inferred but not transparent.

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

Conciseness4/5

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

The description is concise with two sentences, no fluff, and front-loads the purpose. However, it could be slightly more structured to separate parameter guidance, but overall efficient.

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

Completeness1/5

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

Given the high complexity (9 optional parameters, no enums, no output schema, no annotations), the description is severely lacking. It does not explain parameter usage, return values, or interaction effects, making it insufficient for correct tool invocation.

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

Parameters1/5

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

The schema has 9 parameters with no descriptions (0% coverage). The description only mentions the 'action' parameter implicitly through key action names, but ignores the other 8 parameters entirely. It fails to add meaning to most parameters, leaving the agent guessing.

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 clearly states 'Unified system setup and onboarding' and lists key actions, making the tool's purpose unambiguous. It is distinct from sibling tools like manage_alerts or system_diagnostics, which serve different functions.

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 implies use for setup and onboarding, but does not explicitly state when to use or when not to use. It references get_capabilities() for a complete action list, offering partial guidance, but lacks clear alternatives or exclusion criteria.

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

tool_introspectionD

Tool introspection providing detailed description of each tool's function

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNoget_capabilities
tool_nameNo
tool_typeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

D1.8/5.0
Behavior1/5

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

With no annotations, the description must disclose behavior but fails to do so. It does not indicate whether the tool is read-only, has side effects, or requires permissions. The default action 'get_capabilities' suggests querying, but this is not stated, potentially misleading an agent about side effects.

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

Conciseness2/5

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

The description is a single short sentence, but it omits essential details. Conciseness is not beneficial when it leads to under-specification; the description should be longer to include parameter and behavioral context.

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

Completeness1/5

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

Given the tool has 3 parameters, an output schema, and no annotations, the description is severely incomplete. It does not explain what actions are possible, how to use filters, or what the output contains, leaving the agent unable to use the tool correctly.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not explain any of the three parameters ('action', 'tool_name', 'tool_type'). The description adds no meaning beyond the schema, leaving parameter semantics completely unspecified.

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

Purpose3/5

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

The description states the tool provides 'detailed description of each tool's function', which conveys a vague purpose of introspection. It does not specify the verb (e.g., 'retrieve', 'describe') or clearly distinguish from sibling tools like 'system_diagnostics', making the purpose ambiguous.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. The description lacks context about situations where introspection is needed, and no comparison with sibling tools is provided, leaving the agent without decision-making support.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv0.2.11
    • First observedbusiness_analytics_management
    • First observedmanage_alerts
    • First observedmanage_metering
    • First observedslack_management
    • First observedsystem_diagnostics
    • First observedsystem_setup
    • First observedtool_introspection
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.9/5.0

Scored across 7 tools

Disambiguation5/5

Each tool targets a distinct area: cost analytics, alerts, metering, Slack integration, diagnostics, setup, and introspection. There is no functional overlap despite some shared themes like anomaly detection in both analytics and alerts.

Naming Consistency3/5

Tool names use snake_case but mix patterns: some start with 'manage_' (verb_noun) while others are noun_noun (e.g., 'slack_management', 'system_diagnostics'). This inconsistency could confuse an agent about naming conventions.

Tool Count5/5

With 7 tools, the server covers the essential domains (costs, alerts, metering, Slack, system, introspection) without bloat. Each tool earns its place, and the count is well-scoped for the stated purpose.

Completeness4/5

The tool surface is comprehensive for AI spending management, including cost analytics, alerting, metering submission/system, Slack integration, and system upkeep. Minor gaps (e.g., user/role management) exist but do not hinder core workflows.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers