Model Context Protocol (MCP)

Introduction

The Alguna Model Context Protocol (MCP) server lets an AI assistant work inside your Alguna account: look up customers and subscriptions, create products, plans and quotes, issue invoices, define metrics and ingest usage — through natural language, using the same operations as the Public API. Use it when you want an assistant to do billing work for you (or your team) rather than writing an integration.

What is MCP?

Model Context Protocol is an open standard that lets AI assistants connect to external systems through a defined set of tools and resources. Alguna's server provides:

Direct account access — query and change your Alguna data without writing code
Live data — every tool call reads or writes your account as it is now
Core billing coverage — customers, products, pricing, plans and bundles, subscriptions and their versions, invoices, billable metrics and events
Role-bound access — connect with OAuth and the assistant can only do what your Alguna role allows, re-checked on every request; revoke the connection at any time

Actively evolving. The Alguna MCP server is under active development. Tools and behaviour may change as coverage expands. Feedback and bug reports go to support@alguna.io or your shared Slack channel.

Prerequisites

An Alguna account whose role allows whatever the assistant should be able to do. With OAuth the assistant inherits your permissions exactly; with an API key it gets the full tool surface.
An MCP client that supports remote servers — Claude, Cursor, ChatGPT, or any client that can add a custom connector or run mcp-remote.

Actions cannot be undone. Anything the assistant does through a tool — creating customers, subscriptions or invoices, ingesting events, cancelling a subscription — is a real change in your account, and there is no automatic rollback.You are responsible for reviewing what the assistant is about to do, verifying the data it is creating or modifying, and understanding the implications. Keep human-in-the-loop confirmation on for every tool call, and develop against sandbox first.

Connect

The server URL is:

https://api.alguna.io/mcp

With OAuth (recommended)

The server supports OAuth with dynamic client registration, so most clients connect without you handling an API key. The connection signs in as you, is limited to what your role allows on every request, and can be revoked at any time.

Open the MCP page in the dashboard

Go to Settings → Connections → MCP and click Connect a client. It shows the server URL above and the clients currently connected.

Add a custom connector in your AI client

In your client, add a new remote MCP server (the wording varies — “custom connector”, “remote MCP server”, “add integration”) and paste the server URL.

The client redirects you to Alguna to sign in and approve the connection. Once approved it appears under Settings → Connections → MCP, where you can disconnect it later.

With an API key

Clients that cannot do OAuth against a remote server can bridge through mcp-remote, passing an API key in the Authorization header. Requires Node.js 20 or later.

{
  "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 a key from Settings → Connections → Developers → 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 bounded by your role and re-checked on every request. Treat the key as a secret: keep it in environment variables or your client’s secret store, never in a committed config file.

Available tools and resources

The server covers the core of the billing platform: customers, products and pricing, plans and bundles, subscriptions and their versions, invoices, and usage metering. It is a curated subset of the Public API, not a mirror of it — wallets, credits, credit notes, refunds, payments, tax and insights are available over the API but not yet as tools.

If you need a tool that is missing, or a tool behaves incorrectly, contact us on Slack or at support@alguna.io.

Tool names below are the identifiers your client shows when it asks you to approve a call.

Customers

Customer accounts

Tool	What it does
`create_customer_account`	Create a customer with billing details and aliases
`get_customer_account`	Read one customer by ID
`list_customer_accounts`	List customers, paginated and filterable
`update_customer_account`	Change a customer's details

See Customer management.

Subscriptions

Tool	What it does
`create_subscription`	Create a subscription from a plan or inline items
`get_subscription`	Read one subscription
`list_subscriptions`	List subscriptions with filters
`update_subscription`	Change subscription-level settings
`activate_subscription`	Activate a draft subscription
`cancel_subscription`	Cancel a subscription

See Subscriptions.

Subscription versions

Tool	What it does
`create_subscription_version`	Draft a new version with a changed item set
`get_subscription_version`	Read one version
`list_subscription_versions`	List a subscription's versions
`list_subscription_version_items`	List the priced items in a version
`update_subscription_version`	Replace a draft version's contents
`publish_subscription_version`	Publish a draft so it takes effect
`delete_subscription_version`	Discard a draft version

See Versioning.

Products and pricing

Products

Tool	What it does
`create_product`	Add a product to the catalog
`get_product`	Read one product
`list_products`	List products
`update_product`	Change a product

See Configure products.

Plans, bundles and prices

Tool	What it does
`get_plan`	Read one plan
`list_plans`	List plans
`create_price_bundle`	Create a bundle of priced products
`get_price_bundle`	Read one bundle
`list_price_bundles`	List bundles
`update_price_bundle`	Change a bundle
`get_price_with_product`	Read a price together with its product
`get_prices_with_products`	List prices with their products

See Plans and Pricing models.

Invoicing

Invoices

Tool	What it does
`create_invoice`	Create a one-off invoice
`get_invoice`	Read one invoice
`list_invoices`	List invoices with filters
`create_invoice_line_item`	Add a line item to an invoice

See One-off invoices.

Usage metering

Billable metrics and events

Tool	What it does
`ingest_billable_events`	Send usage events (same shape and limits as `POST /events`)
`create_billable_metric`	Define a metric: event name, aggregation, filters
`get_billable_metric`	Read one metric
`list_billable_metrics`	List metrics
`update_billable_metric`	Change a metric's definition

See Define metrics and Send usage events.

Resources

The server also publishes reference documents an assistant can read to understand your data before acting:

Resource	URI
Customer Management Guide	`alguna://docs/customer-management`
Product Configuration Guide	`alguna://docs/product-configuration`
Pricing Models Guide	`alguna://docs/pricing-models`
Subscription Management Guide	`alguna://docs/subscription-management`
Invoice Management Guide	`alguna://docs/invoice-management`
Usage Metering Guide	`alguna://docs/usage-metering`
Filtering and Sorting Guide	`alguna://docs/filtering-sorting`

Clients that support MCP resources load these automatically as context.

How to use it

Once connected, talk to Alguna through your assistant in plain language. The assistant picks the tool, fills in the parameters and — if you keep confirmations on — shows you the call before it runs.

Read first

Start with lookups to see how the assistant maps your words onto tools:

"List all customer accounts"
"Get customer account cust_abc123"
"Find the customer whose alias is acme-user-4821"

"List active subscriptions"
"Show me subscription sub_123 and its current version"
"List subscriptions for customer cust_abc123"

"List overdue invoices"
"Get invoice inv_123"
"List invoices for customer cust_abc123 issued this quarter"

Then write

Give the assistant the same facts you would put in an API request. Missing required fields are asked for.

Create a subscription
Update a customer
Create an invoice

Create a subscription for customer cust_abc123 on plan pln_professional,
starting 2026-07-01 with a 12-month fixed contract, and activate it.

Update customer cust_abc123: rename it to "Acme Corporation",
set the billing address to 1 Market St, San Francisco, CA 94105, US,
and add the alias "crm-001ABC".

Create a one-off invoice for customer cust_abc123 in USD with one line:
"Implementation services", quantity 1, unit price 5000, due in 30 days.

Chain operations

Multi-step requests work, and the assistant carries IDs between calls:

Onboard a customer

Create a customer account for StartupCo with billing email billing@startupco.com
Create a subscription for it on plan pln_starter
Activate the subscription

Change pricing on an existing subscription

Get subscription sub_123 and list its current version's items
Create a new draft version with the platform fee raised to 600
Publish that version effective at the next renewal

Set up usage-based billing

Create a billable metric "API Requests" counting api_request events
Ingest three test api_request events for customer cust_abc123
List billable metrics to confirm

Good habits

Give identifiers

Customer, subscription and invoice IDs (or customer aliases) remove ambiguity and save a lookup round-trip.

Ask for filters

"Overdue invoices for customer X" is one call; "all invoices" is many pages.

Confirm before writing

Read the proposed tool call before approving it. Writes are real and are not rolled back.

Know the boundary

The tool set is a subset of the API. If no tool exists for what you need, the API may still support it.

Errors

Tool failures return the API's error message. Common ones:

Authentication failed — for OAuth, reconnect from Settings → Connections → MCP; for an API key, check that the key is correct and has not been revoked
Permission denied — your role does not allow the action; OAuth connections are bounded by your role and re-checked on every request
Not found — the ID or alias does not exist in this environment (sandbox and production are separate)
Validation error — a required field is missing or a value is invalid; the message names the field. See Errors
Rate limited — wait, then retry

Developer quick start — the same operations over HTTP and the TypeScript SDK
API overview — base URLs, authentication, versioning
How Alguna works — the objects the tools operate on
Automations — event-driven workflows that run inside Alguna without an assistant

Support

Slack, for existing customers
support@alguna.io

​Introduction

​What is MCP?

​Prerequisites

​Connect

​With OAuth (recommended)

​With an API key

​Available tools and resources

​Customers

​Subscriptions

​Products and pricing

​Invoicing

​Usage metering

​Resources

​How to use it

​Read first

​Then write

​Chain operations

​Good habits

Give identifiers

Ask for filters

Confirm before writing

Know the boundary

​Errors

​Related

​Support

Introduction

What is MCP?

Prerequisites

Connect

With OAuth (recommended)

With an API key

Available tools and resources

Customers

Subscriptions

Products and pricing

Invoicing

Usage metering

Resources

How to use it

Read first

Then write

Chain operations

Good habits

Errors

Related

Support