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

​
Subscription Management

​
Product & Pricing

​
Billing & Invoicing

​
Usage & Metering

​
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 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:

​
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: