Skip to main content
EXPERIMENTAL BETA FEATUREThe Alguna MCP server is currently in experimental beta. You may encounter bugs, unexpected behavior, or breaking changes. Use with caution in production environments.We highly encourage feedback and bug reports, and will try to address these as quickly as possible.

​
Introduction

The Alguna Model Context Protocol (MCP) server enables AI assistants to interact directly with your Alguna account, providing seamless access to billing, subscription, and customer data through natural language interfaces.

​
What is MCP?

Model Context Protocol is an open standard that allows AI assistants to securely connect to external data sources and APIs. Alguna's MCP server implementation provides:
  • Direct API Access: Query and manage your Alguna data without writing code
  • Natural Language Interface: Use conversational commands to interact with your billing platform
  • Real-time Data: Access up-to-date information from your Alguna account
  • Full API Coverage: Available functions mirror everything in our public API

​
Prerequisites

Before using the MCP server, ensure you have:
  • An Alguna account with API access enabled
  • An API key generated from your dashboard
  • A supported AI assistant (Claude Desktop, Claude Code, Cursor, or other MCP-compatible clients)
IMPORTANT: Actions Cannot Be UndoneThe MCP server has full access to your Alguna account through your API key. Any actions taken by the AI assistant (creating customers, subscriptions, invoices, etc.) are permanent and cannot be automatically undone.You are responsible for:
  • Reviewing and approving all actions before the AI executes them
  • Verifying the accuracy of data being created or modified
  • Understanding the implications of each operation
We strongly recommend ensuring your tool is using human-in-the-loop flows for every tool being called.

​
Installation & Configuration

The configuration below uses mcp-remote as a temporary solution while more clients add native support for remote MCP servers. This approach is subject to change.

​
Claude Desktop Configuration

Add the following to your Claude Desktop configuration file: 
{
  "mcpServers": {
    "alguna": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.alguna.io/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer your-api-key-here"
      }
    }
  }
}
Replace your-api-key-here with your actual API key from the Alguna dashboard.

​
Authentication

The MCP server requires authentication using your Alguna API key. You can find your API key in the Alguna dashboard under Settings > API Keys.
OAuth authentication support is coming soon as an alternative to API keys.
Keep your API key secure and never commit it to version control. Use environment variables or secure configuration management.

​
Available Tools and Resources

The Alguna MCP server provides access to your billing platform through tools that mirror our public API. Any endpoint available in our public API is accessible through the MCP server.
If there are tools or endpoints you would like added to the MCP server, or if you encounter any issues with existing tools or incorrect behaviors, please contact us via slack or email at [email protected].

​
Available Tool Categories

​
Customer Account Management

  • Create Customer Account: Create new customer accounts with billing information
  • Get Customer Account: Retrieve account details by ID
  • List Customer Accounts: Get paginated list of all accounts
  • Update Customer Account: Modify account information

​
Subscription Management

  • Create Subscription: Create new subscriptions
  • Get Subscription: Retrieve subscription details
  • List Subscriptions: View all subscriptions with filtering
  • Update Subscription: Modify subscription details
  • Activate Subscription: Activate pending subscriptions
  • Cancel Subscription: Cancel active subscriptions
  • Create Subscription Version: Create new version with updated items
  • Get Subscription Version: Retrieve version details
  • List Subscription Versions: View all versions for a subscription
  • Update Subscription Version: Modify version details
  • Publish Subscription Version: Make a version active
  • Delete Subscription Version: Remove draft versions
  • List Subscription Version Items: View items in a version

​
Product & Pricing

  • Create Product: Add new products to your catalog
  • Get Product: Retrieve product details by ID
  • List Products: Browse all products
  • Update Product: Modify product information
  • Get Plan: Retrieve plan details by ID
  • List Plans: View all available plans
  • Create Price Bundle: Create bundled pricing
  • Get Price Bundle: Retrieve bundle details
  • List Price Bundles: View all bundles
  • Update Price Bundle: Modify bundle configuration
  • Get Price with Product: Get price with associated product details
  • Get Prices with Products: List prices with product information

​
Billing & Invoicing

  • Create Invoice: Generate new invoices
  • Get Invoice: Retrieve invoice details by ID
  • List Invoices: View all invoices with filtering
  • Create Invoice Line Item: Add line items to invoices

​
Usage & Metering

  • Ingest Billable Events: Send usage events for metered billing
  • Create Billable Metric: Define new metrics for usage tracking
  • Get Billable Metric: Retrieve metric details by ID
  • List Billable Metrics: View all configured metrics
  • Update Billable Metric: Modify metric configurations

​
Contextual Resources

The MCP server provides contextual resources that AI agents can use to better understand your data and guide you:
  • Pricing Models Guide: Reference for different pricing model configurations
  • Customer Management Guide: Best practices for customer account management
  • Product Configuration Guide: How to set up and configure products
  • Subscription Management Guide: Managing subscription lifecycles
  • Invoice Management Guide: Invoice creation and management workflows
  • Usage Metering Guide: Setting up and tracking usage-based billing
  • Filtering Guide: How to use filters when querying data
These resources are automatically available as context for AI agents when processing your requests.

​
How to Use

Once configured, you can interact with Alguna through natural language commands in your AI assistant. Here are common usage patterns and examples:

​
Basic Commands

Start with simple queries to explore your data: 
"List all customer accounts"
"Get customer account with ID acc_123"
"Find customer by name Acme Corp"

​
Advanced Operations

Perform complex operations with detailed instructions:
  • Create Subscription
  • Update Customer
  • Create Invoice
Create a new subscription for customer account acc_ABC123 with:
- Plan ID: plan_professional
- Start date: 2024-01-01
- Billing period: monthly

​
Workflow Examples

Combine multiple operations for complete workflows: 
1. Create a new customer account for StartupCo
2. Create a product for their specific needs
3. Create a plan including that product
4. Create a subscription with the new plan
5. Activate the subscription

1. Get subscription details for sub_123
2. Create a new subscription version with updated items
3. Publish the subscription version to make it active
4. Cancel the old subscription if needed

1. Create a billable metric for API calls
2. Ingest usage events for customer accounts
3. Create invoice with usage-based line items
4. List invoices to verify billing

​
Best Practices

Be Specific

Provide clear identifiers like account IDs, subscription IDs, or invoice IDs when available

Use Filters

Use pagination and filtering parameters when listing resources

Verify Changes

Always confirm details before making updates or creating new records

Understand Limitations

Tools mirror our public API currently - if it's not in the API, it's not available via MCP. Subject to change as we continue to expand the MCP server.

​
Error Handling

The MCP server provides clear error messages when operations fail:
Common errors and their solutions:
  • Authentication Failed: Verify your API key is correct and has necessary permissions
  • Resource Not Found: Check that the ID or identifier exists in your account
  • Validation Error: Ensure all required fields are provided with valid values
  • Rate Limit Exceeded: Wait before making additional requests

​
Support

For support with the MCP server:
⌘I