Metadata-Version: 2.4
Name: revenium-mcp
Version: 0.2.8
Summary: Model Context Protocol (MCP) server for Revenium API monitoring, analytics, and AI spending management
Author-email: Revenium Team <support@revenium.io>
Maintainer-email: Revenium Team <support@revenium.io>
License-Expression: MIT
Project-URL: Homepage, https://github.com/revenium/revenium-mcp
Project-URL: Documentation, https://github.com/revenium/revenium-mcp#readme
Project-URL: Repository, https://github.com/revenium/revenium-mcp
Project-URL: Bug Tracker, https://github.com/revenium/revenium-mcp/issues
Keywords: mcp,revenium,api,ai,assistant,cli,server,model-context-protocol,anthropic,claude
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Framework :: AsyncIO
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp<4.0.0,>=3.2.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: structlog>=23.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: revenium-middleware-openai>=0.4.6
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: diskcache>=5.6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: psutil>=5.9.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: requests-mock>=1.10.0; extra == "test"
Requires-Dist: psutil>=5.9.0; extra == "test"
Dynamic: license-file

[![PyPI version](https://img.shields.io/pypi/v/revenium-mcp.svg)](https://pypi.org/project/revenium-mcp/)
[![Python Versions](https://img.shields.io/pypi/pyversions/revenium-mcp.svg)](https://pypi.org/project/revenium-mcp/)
[![Documentation](https://img.shields.io/badge/docs-revenium.io-blue)](https://docs.revenium.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP 2025-06-18](https://img.shields.io/badge/MCP-2025--06--18-purple)](https://modelcontextprotocol.io/specification/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 (17 tools):** All Starter tools plus product management, customer management, subscriptions, billing, tool registry

## Getting Started

### For Claude Code Users (Recommended)

1. **Install uv:**
   ```bash
   pip install uv
   ```

2. **Add to Claude Code:**
   ```bash
   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:**
   ```bash
   pip install uv
   ```

2. **Create .env file:**
   ```bash
   cat > .env << EOF
   REVENIUM_API_KEY=hak_your_api_key_here
   TOOL_PROFILE=starter
   EOF
   ```

3. **Run the server:**
   ```bash
   uvx revenium-mcp
   ```

See [Installation](#installation) for Cursor, Augment, and other integrations.

## MCP Specification

Implements [Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18) version **2025-06-18**.

- **Framework:** FastMCP 3.2+
- **Transport:** stdio
- **Protocol:** JSON-RPC 2.0

## Requirements

### Prerequisites

- **Python 3.11+** with pip
- **Your Revenium API key** (get one at [ai.revenium.io](https://ai.revenium.io))
- **Optional:** [uv/uvx](https://github.com/astral-sh/uv) 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](https://www.revenium.ai/privacy-policy)

## AI Query Routing (Optional Feature)

The MCP server includes an **optional** AI-powered query routing feature for natural language interpretation. **This feature is disabled by default** and is not required for normal operation.

### What It Does

When enabled, the server can use OpenAI's API to interpret natural language queries and route them to appropriate tools. This is an experimental feature that adds intelligent query understanding.

### Self-Metering

When AI routing is enabled, the MCP server automatically tracks its own OpenAI usage back to your Revenium account:
- Uses `revenium-middleware-openai` to meter its own API calls
- Creates transactions visible in your Revenium dashboard
- Provides full transparency into the MCP server's operational costs

### Enabling AI Routing

AI routing is **disabled by default**. To enable it, add to your `.env` file:

```bash
# .env
REVENIUM_API_KEY=hak_your_api_key_here
OPENAI_API_KEY=sk-your_openai_key_here
AI_ROUTING_ENABLED=true
AI_MODEL_NAME=gpt-3.5-turbo  # Optional: default model
```

Then run:
```bash
uvx revenium-mcp
```

**Note:** Without AI routing enabled, the MCP operates normally using direct tool calls. No OpenAI API key or additional costs are required.

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

### Install Python Package

**Option 1: Installation with uvx** (Recommended for local testing)
```bash
# 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**

```bash
# 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** | 17 tools | Full platform | Product & subscription management, usage-based billing, comprehensive analytics, tool registry |

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

**With uvx and .env file:**
```bash
# 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 (17 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**
```bash
# 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**
```bash
# 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](https://github.com/revenium/revenium-mcp/tree/HEAD/.claude/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:**
```bash
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:**
```json
{
  "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](#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 Slack integrations. When `REVENIUM_BASE_URL` points at a non-production environment, set this too — otherwise analytics calls default to production and fail with 401 for non-prod API keys. | `https://ai.revenium.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):**
```bash
# 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:**
```bash
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](https://docs.revenium.io)

Additional resources:
- [API Documentation](https://revenium.readme.io)
- [MCP Protocol Specification](https://modelcontextprotocol.io)

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](./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](./CODE_OF_CONDUCT.md) for details.

## Security

Security is a top priority. For security concerns, please see [SECURITY.md](./SECURITY.md) for:

- Our security policy
- How to report vulnerabilities
- Security best practices

## License

This project is licensed under the MIT License. See [LICENSE](./LICENSE) for full details.

## Support

For questions, issues, or feature requests:

- **Email:** support@revenium.io
- **Issues:** [GitHub Issues](https://github.com/revenium/revenium-mcp/issues)
- **Documentation:** [docs.revenium.io](https://docs.revenium.io)
- **Community:** [Revenium Discord](https://discord.gg/revenium) (coming soon)

## Development

### Local Development Setup

```bash
# 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

```bash
# 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](./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
