Skip to navigation

Developing for Solvimon

Use LLMs and AI coding agents to build your Solvimon integration: machine-readable docs, an installable agent skill, plus an MCP server that lets your agent call the Solvimon API directly.

Looking to use Claude as a billing copilot rather than build an integration? See the Claude integration instead.


Using the documentation with LLMs

llms.txt

The llms.txt standard helps LLMs index documentation efficiently, similar to how a sitemap helps search engines. We host two files:

Paste either URL into your AI tool, or reference it from your agent’s instructions file (for example CLAUDE.md or .cursorrules):

Agent instructions
When working on Solvimon billing code, consult https://docs.solvimon.com/llms.txt
to find the relevant documentation pages.

The Solvimon agent skill

Agent Skills are instruction files that coding agents such as Claude Code load on demand. The solvimon skill gives your agent a working knowledge of the platform: the API surface across all four domains, status lifecycles, the meter-to-invoice setup workflow, event ingestion semantics, and common pitfalls like invoice grace periods and asynchronous event deduplication.

Install it with the skills CLI:

npx skills add https://docs.solvimon.com

The skill pairs well with the MCP server below: the skill tells your agent how Solvimon works, and the MCP server lets it act on your sandbox.

The Solvimon MCP server

The Model Context Protocol (MCP) is an open standard that lets AI tools call external services. The Solvimon MCP server exposes the Solvimon API as a set of tools, so a coding agent can create meters, pricing plans, and test customers in your sandbox while you build, instead of you hand-writing API calls to set up test data.

The server runs at https://test.mcp.solvimon.com and authenticates with OAuth. Add the URL to your agent, sign in with your Solvimon Desk account in the browser, and approve access. There is no API key to copy, and the agent gets exactly the permissions that you have in Desk.

Test environment. The test.mcp.solvimon.com endpoint connects to your test sandbox, so agents can experiment freely without touching live billing data. Production access (https://mcp.solvimon.com) is enabled per account; contact us to get set up. The production server reads everything and lets a signed-in user draft quotes and customers, but it can’t send, accept, convert or bill anything, see Access modes. Each server only acts on platforms of its own environment: the test server never touches a live platform, and the other way around.

Connect your coding agent

Add the server by URL:

Add Solvimon's MCP to Claude Code
claude mcp add --transport http solvimon-test https://test.mcp.solvimon.com

Then run /mcp inside Claude Code, select solvimon-test, and choose Authenticate to sign in.

Choose a platform

If you approved access to more than one platform during sign-in, the server will not pick one for you. Name the platform with an X-PLATFORM-ID header. You find the platform ID in the Desk address bar: it is the part of the path that starts with plat_, for example https://test.desk.solvimon.com/plat_.../overview.

Claude Code
claude mcp remove solvimon-test
claude mcp add --transport http solvimon-test https://test.mcp.solvimon.com --header "X-PLATFORM-ID: <platformId>"
Cursor / VS Code
"solvimon-test": {
"url": "https://test.mcp.solvimon.com",
"headers": { "X-PLATFORM-ID": "<platformId>" }
}

The header pins every call on the connection to one platform. To keep access to several platforms, leave it out and let the agent pass platform_id on each tool call instead, see Tool reference.

In non-interactive environments such as CI, nobody can sign in through a browser. There, send a test API key (Desk → Developers → API keys) in the X-API-KEY header. A test key only works against the test endpoint. On the production server an API key only reads; drafting needs the OAuth sign-in.

Claude Code
claude mcp add --transport http solvimon-test https://test.mcp.solvimon.com --header "X-API-KEY: <apiKey>"
Cursor / VS Code
"solvimon-test": {
"url": "https://test.mcp.solvimon.com",
"headers": { "X-API-KEY": "<apiKey>" }
}

For Claude Desktop and claude.ai setup, see the Claude integration.


Access modes

The two servers expose a different set of tools.

ServerModeWhat an agent can do
test.mcp.solvimon.comRead and writeEvery tool below: build catalogs, plans, meters, customers, subscriptions, quotes, invoices, webhooks and more in your test sandbox.
mcp.solvimon.comRead and draftEvery read tool, plus drafting: create_quote, import_order_form, and the draft actions of write_quote and write_customer.

Reads are the same on test and live. Every read tool is served on both servers, including users, audit records, reports, settings, payments, integrations, webhooks, usage limits, operations and the billing run. The only exceptions are solvimon_api_call (the raw API passthrough, which can reach any endpoint) and the two guided flows start_onboarding and start_migration (every step they hand out is a write). Those three are on the test server only.

Drafting on live keeps everything in DRAFT. On mcp.solvimon.com a signed-in user can:

  • create a customer (always DRAFT) and edit it while it is DRAFT;
  • create a quote, edit a quote, version, schedule, contract terms, price overrides, direct pricings and attachments while the version is DRAFT;
  • turn a signed order form into a DRAFT quote with import_order_form;
  • finalize the latest DRAFT version of a quote, after an explicit confirmation. The agent first shows what finalizing does and whether it needs approval, see Finalize.

Everything after that is done in Solvimon Desk: sending, accepting, rejecting, signing, converting a quote into a subscription, activating, archiving or deleting a quote or customer, contacts, custom field definitions and pricing plans. The agent says so and gives you the Desk link.

Some rules apply on live:

  • Drafting needs an OAuth sign-in. An API key on the production server only reads.
  • If you connected before drafting was available, your token only reads. Disconnect and reconnect to get the drafting tools.
  • Your own Desk role still applies. A sales rep with the Customer Draft Contributor role, for example, can only create DRAFT customers.
  • Endpoints that return secrets (an API key’s value, a webhook’s signing secret) are refused by every tool on both servers.

Write access on live beyond drafting is enabled per customer, on request; contact us to ask for it.


Tool reference

Every tool has its own page under Tools in the menu on the left, with its actions, guardrails and an example call. The tables below list them all.

Tools come in pairs: a read tool (get_*) that never changes data, and a write tool (write_*, create_*, import_*, forget_customer) that does. Keeping reads and writes apart lets you allow an agent to explore freely while still approving every change. Every write tool checks the action against its own list on the server, so a client can’t reach an action the tool doesn’t advertise.

Most tools follow the same input pattern:

FieldMeaning
actionWhat to do: list, get, search, create, update, and tool-specific actions
resource_typeWhich resource, for tools that cover more than one
idResource id or reference, for single-resource actions
bodyRequest body for create/update, same shape as the REST API
filterQuery params for list actions as string key/value pairs, e.g. {"limit": "20"}
platform_idWhich platform to act on. Only necessary when an OAuth authorization granted access to more than one platform. Omit it on an API-key connection.
confirmedOn confirm-first actions (inviting a user, creating a billing entity or quote template, finalizing on live): without true the tool returns what it would do and writes nothing

The Live column below shows what the production server serves: Read, Draft (only the draft actions), or – (test server only).

Overview

Account and setup

ToolWhat it doesLive
get_solvimon_accountVerify the connection and list billing entities. Call first.Read
get_settingsRead how the platform is configured: invoicing, quotes, currencies, custom fields, processing statusRead
get_billing_entitiesRead billing entities and their tax registrationsRead
write_billing_entityCreate or update a billing entity. Add or remove tax registrations–
get_usersRead your Solvimon users, roles, teams, SSO providers and API key metadataRead
write_userInvite a person or change a user’s roles–
get_integrationsRead the status of payment, e-invoicing, tax, ERP, email and export integrationsRead

Product catalog and pricing

ToolWhat it doesLive
get_product_catalogRead product categories, products, product items, features, coupons and promotion codesRead
write_product_catalogCreate and manage the catalog, coupons and promotion codes–
get_pricing_plansRead pricing plans, plan versions and plan groupsRead
write_pricing_planCreate pricing plans and plan versions–
get_agent_contextRead the agent guidance stored on a plan, product, item or quote templateRead
write_agent_contextPropose and save that agent guidance–

Metering and usage limits

ToolWhat it doesLive
get_meteringRead meters, usage events and uploads. Trace why an event is (not) billedRead
write_meteringIngest usage events. Create, update and delete meter config–
create_meter_setupShortcut: meter, meter value, and calculation in one call–
get_usage_limitsRead usage limits, their live status, alert rules and alertsRead
write_usage_limitCreate, update, activate or archive usage limits–

Customers and subscriptions

ToolWhat it doesLive
get_customersList, get or search customers. Entitlements, contacts, seats, shipping addresses, VAT checkRead
write_customerCreate and manage customers and their contactsDraft
forget_customerGDPR erasure of a customer’s personal data–
get_subscriptionsRead subscriptions, subscription groups and schedulesRead
write_subscriptionCreate and manage subscriptions and ramps, including init, cancel and void–
create_checkout_linkHosted checkout URL for self-serve signup–

Quotes

ToolWhat it doesLive
get_quotesRead quotes, versions, schedules, templates and approvals. Quote PDF, approval evaluation, your approvalsRead
create_quoteBuild a DRAFT quote in one call, including ramps and price overrides, with a validate-first dry runDraft
import_order_formTurn a signed order form into a DRAFT quote, reconciled line by lineDraft
write_quoteEdit quotes and move them through finalize → accept → subscription, plus signingDraft
write_quote_templateCreate and manage quote templates–
get_documentsFind attachments and get download linksRead
write_documentsUpload, attach, detach and delete documents–

Ramps, price and entitlement overrides, direct pricing, payment terms, quote text, finalizing, signing and upgrade quotes are explained in Quote features.

Invoicing and payments

ToolWhat it doesLive
get_invoicesRead, search or preview invoices. PDF, UBL and e-invoice documentsRead
write_invoiceCreate one-off invoices line by line, finalize, pay, credit, refund and send–
get_paymentsRead payment methods, acceptors, requests, payments and payment schedulesRead
get_billing_runHealth of a month’s billing run, and a preflight before a bulk finalizeRead

Wallets and credits

ToolWhat it doesLive
get_wallets_creditsRead credit types, wallet types, wallets, balances, grants and auto top-upsRead
write_wallets_creditCreate and manage credit types, wallet types and wallets–

Automation, operations and audit

ToolWhat it doesLive
get_workflowsRead workflows, their actions, triggers and executionsRead
get_webhooksRead webhook endpoints, subscribable events and deliveriesRead
write_webhookCreate, update and deactivate webhook endpoints–
get_operationsRead portal links, bulk actions and reprocessesRead
get_audit_recordsWho changed what, and whenRead
get_reportsRead and generate CSV/Parquet reportsRead

Analytics, docs and helpers

ToolWhat it doesLive
analyticsRead-only queries on dashboard data (revenue, MRR, churn, usage)Read
search_docsSearch these public docsRead
show_cardShow an invoice, customer, quote, subscription, product or plan as a visual cardRead
get_more_toolsReport a request no tool coversRead
start_onboardingGuided sandbox onboarding to your first invoice preview–
start_migrationGuided migration from Stripe Billing–
solvimon_api_callRead-only raw API passthrough for anything not covered above–

A typical setup flow chains the tools in dependency order:

get_solvimon_account → write_product_catalog → create_meter_setup (if usage-based)
→ write_pricing_plan → create_checkout_link or write_subscription (init)

A typical sales flow:

Typical sales flow
get_customers → get_pricing_plans → create_quote (validate, then apply)
→ write_quote (finalize) → accept, sign and convert (write_quote on test, Desk on live)

Desk links. Every record a tool returns that has a page in Solvimon Desk carries a desk_url. The agent is told to hand you that link instead of a bare id, and never to build a Desk URL itself. Results without an id of their own link to what they created: create_quote and import_order_form to the quote, create_checkout_link to its subscription, create_meter_setup to its meter. Product items and meter value calculations have no Desk page and so no link.

Cards. In clients that support MCP Apps, such as Claude, a single invoice, customer, quote, subscription, product or pricing plan is shown as a visual card. Lists and searches show no card. Clients without MCP Apps show the card’s text summary instead.

  • A successful write on one of those records shows its card again, so you see the result.
  • Write tools take an optional show_card boolean. false skips the card for that call. In a multi-step build the agent passes false on every step but the last, or calls show_card once at the end.
  • Adding or removing invoice lines (write_invoice add_line / delete_line) never shows a card. It returns a short summary of the totals instead.
  • Card buttons that change something, such as Finalise on a draft invoice, first ask you to confirm. For a user who can’t make that change, the button is a link to Desk.
  • A FINAL quote card has + Add signer. A draft or final quote card has Preview first invoice.