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:
- docs.solvimon.com/llms.txt lists every page in these docs with a short description, so an agent can find and fetch the pages it needs.
- docs.solvimon.com/llms-full.txt contains the full documentation in a single file, useful for loading everything into a model’s context at once.
Paste either URL into your AI tool, or reference it from your agent’s instructions file (for example CLAUDE.md or .cursorrules):
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:
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
Claude Code
Cursor
VS Code
Add the server by URL:
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.
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.
Use an API key instead
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.
For Claude Desktop and claude.ai setup, see the Claude integration.
Access modes
The two servers expose a different set of tools.
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:
The Live column below shows what the production server serves: Read, Draft (only the draft actions), or – (test server only).
Overview
Account and setup
Product catalog and pricing
Metering and usage limits
Customers and subscriptions
Quotes
Ramps, price and entitlement overrides, direct pricing, payment terms, quote text, finalizing, signing and upgrade quotes are explained in Quote features.
Invoicing and payments
Wallets and credits
Automation, operations and audit
Analytics, docs and helpers
A typical setup flow chains the tools in dependency order:
A typical sales flow:
Desk links and cards
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_cardboolean.falseskips the card for that call. In a multi-step build the agent passesfalseon every step but the last, or callsshow_cardonce at the end. - Adding or removing invoice lines (
write_invoiceadd_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.