Model Context Protocol (MCP)

Actively evolvingThe Alguna MCP server is under active development. Tools and behavior may change as we expand coverage.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
Role-Bound Access: Connect with OAuth and the assistant can only do what your Alguna role allows, re-checked on every request — revoke access at any time

Prerequisites

Before using the MCP server, ensure you have:

An Alguna account with the role permissions for whatever the AI assistant should be able to do
A supported AI assistant (Claude, Cursor, ChatGPT, or another MCP client that supports remote servers)

IMPORTANT: Actions Cannot Be UndoneAny 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

Connect with OAuth (recommended)

Alguna’s MCP server supports OAuth, so most clients can connect without ever handling an API key. The connection signs in as you, so it can only do what your role allows, and you can revoke it at any time.

Open Settings > Connections in the Alguna dashboard

Go to Settings > Connections > MCP and click Connect a client. This shows your server URL: https://api.alguna.io/mcp.

Add a custom connector in your AI client

In your MCP client (Claude, Cursor, ChatGPT, etc.), add a new custom connector and paste in the server URL above.

Your client will redirect you to Alguna to sign in and approve the connection. Once approved, it appears in Settings > Connections > MCP, where you can disconnect it at any time.

Exact steps for adding a custom/remote connector vary by client — consult your AI client’s documentation for how it refers to remote MCP servers.

Manual configuration (API key)

Some clients don’t yet support OAuth-based remote connectors natively. For those, connect with an API key using mcp-remote as a bridge.

This configuration requires Node.js 20 or higher to be installed.

Add the following to your client’s MCP configuration file (for example, Claude Desktop’s config):

{
  "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 an API key from Settings > API Keys.

API keys are not scoped to a role — a connection authenticated this way gets the full tool surface, unlike an OAuth connection, which is limited to what your role allows and re-checked on every request. 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 support@alguna.io.

Available Tool Categories

Customer Account Management

Account Operations

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

Subscription Operations

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

Subscription Versions

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

Product Catalog

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

Plans & Pricing

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

Invoice Management

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

Billable Metrics

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"

"List all subscriptions"
"Get subscription details for sub_123"
"List subscriptions for customer account acc_123"

"List all invoices"
"Get invoice details for inv_123"
"List invoices for customer account acc_123"

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

Update customer account acc_123:
- Change name to "Acme Corporation"
- Update billing address
- Add external alias for integration

Create an invoice for customer account acc_123 with:
- Line item: Professional services for $5,000
- Due date: 30 days from now
- Description: Implementation services

Workflow Examples

Combine multiple operations for complete workflows:

Customer Onboarding

Create a new customer account for StartupCo
Create a product for their specific needs
Create a plan including that product
Create a subscription with the new plan
Activate the subscription

Subscription Management

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

Usage-Based Billing

Create a billable metric for API calls
Ingest usage events for customer accounts
Create invoice with usage-based line items
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: For OAuth connections, reconnect from Settings > Connections > MCP; for API keys, verify the key is correct and hasn't been revoked
Permission Denied: Your role doesn't allow that action — OAuth connections are bounded by your role and re-checked on every request
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:

Contact us through Slack (for existing customers)
Email support at support@alguna.io

​Introduction

​What is MCP?

​Prerequisites

​Installation & Configuration

​Connect with OAuth (recommended)

​Manual configuration (API key)

​Available Tools and Resources

​Available Tool Categories

​Customer Account Management

​Subscription Management

​Product & Pricing

​Billing & Invoicing

​Usage & Metering

​Contextual Resources

​How to Use

​Basic Commands

​Advanced Operations

​Workflow Examples

​Best Practices

Be Specific

Use Filters

Verify Changes

Understand Limitations

​Error Handling

​Support

Introduction

What is MCP?

Prerequisites

Installation & Configuration

Connect with OAuth (recommended)

Manual configuration (API key)

Available Tools and Resources

Available Tool Categories

Customer Account Management

Subscription Management

Product & Pricing

Billing & Invoicing

Usage & Metering

Contextual Resources

How to Use

Basic Commands

Advanced Operations

Workflow Examples

Best Practices

Error Handling

Support