ProAbono MCP Installation
A local MCP server that installs ProAbono into your site, from your IDE.
It gives your coding assistant the ProAbono documentation, the API Live contract and your own ProAbono configuration, so it can run the In-Site installation with you end to end, generate integration code already filled in with your real business identifier, Segment, offers and Features, read your account back to verify the result, and answer API questions from the real contract instead of guessing.
It runs locally, over stdio, against whatever account your credentials open. It has no environment concept of its own: your credentials are the only boundary.
Install
Claude Code
claude mcp add --transport stdio proabono --scope user -- npx -y @proabono/mcp-installation
VS Code
In .vscode/mcp.json:
{
"servers": {
"proabono": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@proabono/mcp-installation"]
}
}
}
Cursor
In .cursor/mcp.json (or ~/.cursor/mcp.json for every project):
{
"mcpServers": {
"proabono": {
"command": "npx",
"args": ["-y", "@proabono/mcp-installation"]
}
}
}
Requires Node.js 20 or later.
Configuration
The server reads seven environment variables and nothing else. It refuses to start if any is missing, naming the ones it needs.
| Variable | Holds |
|---|
PROABONO_API_BASE | The API endpoint, https://api-{business_id}.proabono.com |
PROABONO_BUSINESS_ID | Your numeric business identifier |
PROABONO_SEGMENT_REF | The Segment your customers and offers belong to |
PROABONO_AGENT_KEY | Basic auth username |
PROABONO_API_KEY | Basic auth password |
PROABONO_PORTAL_SECRET | HMAC key for the portal security hash |
PROABONO_WEBHOOK_SECRET | Secret for the notification signature |
All seven are in your ProAbono BackOffice, on one page: Integration → MCP. PROABONO_API_BASE must begin with https://, and PROABONO_BUSINESS_ID must be digits only.
Put them in the env block of your MCP client entry, in a file git ignores. That keeps each set of seven attached to one project and one ProAbono account — which is what you need once you have two sets, since sandbox and production are two accounts with different endpoints, identifiers and keys. Declare one entry per account, for example proabono-sandbox and proabono-production, each with its own env.
.vscode/mcp.json and .cursor/mcp.json sit inside your repository: add them to .gitignore before pasting a value into them. Cursor also reads ~/.cursor/mcp.json, outside every repository.- Claude Code:
--scope user keeps the entry outside the repository. A project .mcp.json is normally committed, so write ${PROABONO_API_KEY} and the other six there instead of the values — Claude Code expands them from your environment.
- VS Code can also prompt for a value through the
inputs section of mcp.json, which keeps it out of the file.
- Avoid shell exports: they hold one set per shell and per machine, and hand your production keys to every project you open.
- The server does not read a
.env file. It reads its process environment only.
No value you supply is ever logged, returned by a tool, put in an error message, or inlined into generated code. Generated code references the variable names.
First prompt
With the server added and the seven variables set, open your project and paste this into your assistant:
Help me install ProAbono in this project.
1. Call get_server_info to confirm the server is reachable, and tell me which version you are talking to.
2. Call installation_status to see whether an installation was already started here.
3. Run install_insite: tell me which stack you detected and why, check the prerequisites with me, then take me through the three In-Site steps and the notification endpoint in order, placing the generated code where my signed-in user is known.
4. List what I still have to do by hand in the ProAbono BackOffice.
5. When the code is in place, run verify_insite_installation and walk me through the go-live checklist.
Answer every question about the ProAbono API from search_documentation and get_api_reference, never from memory.
When it works, step 1 answers with the server version and a configuration whose status is complete, listing the seven variable names — never a value. If the ProAbono tools are not there at all, the server refused to start: a variable is missing, and the error naming it is in your MCP client's log. get_server_info never reports an incomplete configuration, because the server does not start on one.
The generators return code and edit none of your files; your assistant places it. The one file the server writes is .proabono/installation.json, the installation state: it carries no credential, is meant to be committed so a later session resumes where this one stopped, and is not written when a tool is called with record_state: false.
Point your keys at a Sandbox account to run this. verify_insite_installation makes sure the customer it verifies against exists — it creates one under an mcp-verify- reference when you name none — and the tools that usually come next — create_update_customer, create_subscription, the Usage writes, bill_customer — create real data in whatever account your credentials open.
Example prompts
Once the installation is under way, these are the questions a developer asks next. Your assistant picks the tools; the second column is the ones it usually reaches for.
| You ask | Tools it usually triggers |
|---|
| "Which offers does my Segment expose, and which Features do they carry?" | list_offers, list_features |
| "Generate a pricing table over my real offers for this page, identified so a signed-in customer can subscribe in place." | generate_pricing_table |
| "Someone else started the ProAbono installation in this project. Where does it stand, and what is left in the BackOffice?" | installation_status |
| "Wire the notification endpoint into this app, and tell me how to activate it in the BackOffice." | scaffold_notification_endpoint |
| "Plan the portal lifecycle for me: upgrade, downgrade, dunning." | plan_integration |
| "Create a customer, subscribe them to my first offer, and show me their Usages." | create_update_customer, create_subscription, get_usages |
| "What would it cost this customer to go from 5 to 10 seats, and is it allowed?" | quote_usage_change |
| "Which endpoint lists a customer's invoices, and what does it return? Write the call in Go." | search_documentation, get_api_reference, generate_integration_code |
What it covers today
The version you installed is in CHANGELOG.md, and get_server_info reports it:
- The three In-Site steps, end to end: the Customer Portal embed with its security hash, the Subscription Workflow round trip, and the Usage synchronization with its cache, its gate and its resynchronization.
- The notification endpoint, with signature verification, deduplication and the BackOffice procedure that activates it.
- Verification: steps 2 and 3 exercised against your account, the go-live rules checked against your own files, and the twelve-item checklist.
- Catalogue and account introspection: offers, Features, customers, subscriptions, Usages, invoices.
- Writes across the lifecycle: customers and their settings, billing addresses, subscriptions and each of their four transitions, Usage writes for all three Feature types, balance lines and billing.
- Documentation and API reference: natural-language search over the ProAbono corpus and the API Live contract.
Not in it, and planned: advanced In-Site options — CSS customization of the hosted pages, and further specific workflows.
Widget and plug-in installations (WordPress and similar) are out of scope by design: this server installs ProAbono In-Site, by code, whatever your stack would lend itself to.
Offers, Features, webhooks, pricing pages and the workflow redirect URL are configured in your ProAbono BackOffice, and the API cannot create them: the server reads them, names what is missing, and gives you the BackOffice path.
Writes marks a tool that changes data in the account your credentials open. It runs as soon as your assistant calls it, with no confirmation step: your credentials are the only boundary.
Documentation
| Tool | What it does | Writes |
|---|
search_documentation | Natural-language search across the ProAbono documentation and the API Live contract. | |
get_api_reference | Parameters and schema for a given endpoint or object. | |
Installation
| Tool | What it does | Writes |
|---|
install_insite | The whole In-Site installation, end to end: stack detection, the prerequisites gate, the three steps in order, and the progress recorded in .proabono/installation.json. | |
installation_status | Where the installation stands: what is done, what was generated where, what is pending in the BackOffice, what was skipped. | |
install_customer_portal | The Step 1 in-site embed, with the security hash, for your stack. | |
link_subscription_workflow | Step 2: the encrypted query read from Links, both ways of opening a workflow, and the single return route covering all five outcomes. | |
sync_usage_rights | The Step 3 rights module: the Usage read, the cache and its expiry, the gate, the write-back for a Feature your application changes, and the resynchronization. | |
scaffold_notification_endpoint | The webhook endpoint: signature verification, the validation handshake, deduplication, a fast acknowledgement, and the BackOffice procedure that activates it. | |
verify_insite_installation | Steps 2 and 3 exercised against your account — on the customer you name, created if missing, or on a new one — the go-live rules checked against your files, and the twelve-item checklist. | yes |
Code generation
| Tool | What it does | Writes |
|---|
generate_pricing_table | A pricing table over your real offers. | |
plan_integration | The ordered plan for a journey: installation, subscription funnel, portal lifecycle, usage metering, notifications. | |
generate_integration_code | Code for a task in the language you name, from the contract and the documentation. | |
Catalogue
| Tool | What it does | Writes |
|---|
list_offers | The offers your Segment exposes. | |
list_offers_for_customer | The offers one customer may take, and the upgrade options of a running subscription. | |
get_offer | A single offer by reference. | |
list_features | The Features of your Business. | |
Customers
| Tool | What it does | Writes |
|---|
get_customer | A customer by reference. | |
create_update_customer | Create a customer, or update one that already carries the reference. One tool: the endpoint is an upsert. | yes |
get_billing_address | The address invoices are issued against. | |
update_billing_address | Update that address, changing only the fields you supply. | yes |
get_payment_settings | Payment type, billing mode, grey-list flag, invoice note and next billing date, in one read. | |
set_next_billing_date | Set the date of the customer's next billing. | yes |
set_invoice_note | Set the note printed at the bottom of every upcoming invoice of the customer. | yes |
set_payment_method | Record a manual payment method; Card and DirectDebit are driven by the payment gateway. | yes |
anonymize_customer | Irreversible. The GDPR erasure path: it erases the personal data and keeps the invoices and the subscription history. ProAbono refuses it while the customer has an invoice due, and erases nothing. | yes |
Subscriptions
| Tool | What it does | Writes |
|---|
get_subscription, list_subscriptions | What a customer is subscribed to. | |
create_subscription | Subscribe a customer to an offer. | yes |
start_subscription | Start a draft subscription, or restart a suspended one. | yes |
upgrade_subscription | Move a subscription to another offer. | yes |
suspend_subscription | Suspend it; start_subscription reverses that. | yes |
terminate_subscription | Terminate it, at the end of the term by default. | yes |
Usage and rights
| Tool | What it does | Writes |
|---|
get_usages | A customer's current Usages, as ProAbono sees them. | |
quote_usage_change | Price an intended change, and check it is allowed, before applying it. | |
push_usage_increment | Report consumption of a Consumption Feature. | yes |
push_usage_quantity | Set the provisioned quantity of a Limitation Feature. | yes |
push_usage_enabling | Switch an OnOff Feature. | yes |
Invoicing and balance
| Tool | What it does | Writes |
|---|
get_invoice | A debit invoice, with its PDF URL when it publishes one — an invoice read right after it is issued may not publish one yet. | |
get_credit_note | A credit note, with its TypeCredit, its reason and its PDF URL when it publishes one. | |
list_invoices | A customer's billing documents, both kinds together. | |
create_balance_line | A debit, or a credit when the amount is negative. | yes |
bill_customer | Invoice whatever is sitting in the balance. | yes |
Server
| Tool | What it does | Writes |
|---|
get_server_info | Version and configuration status, values excluded. | |
No tool in this server destroys billing history: deleting a customer, a subscription or an invoice is out of scope in any account, and ProAbono's customer-suspension, invalidation and link-revocation endpoints exist and are deliberately not exposed. anonymize_customer is the one tool whose effect cannot be undone, and it is not a destruction — it erases personal data and keeps the invoices and the subscription history, which is what a GDPR erasure asks of a billing system.
Troubleshooting
| Symptom | Cause | Fix |
|---|
| The ProAbono tools do not appear in your assistant, and your MCP client's log says a configuration variable is missing | The server refused to start: a variable is missing or empty | Set every variable the message names in the env block of the entry, then restart the client |
The log says PROABONO_API_BASE must be an https:// endpoint | The endpoint does not begin with https:// | Use https://api-{business_id}.proabono.com, with your own business identifier |
The log says PROABONO_BUSINESS_ID must be the numeric business identifier | The identifier holds something other than digits | Keep the digits only: no prefix, no quotes, no spaces |
A tool answers ProAbono API error 401 | The Agent key or the API key is wrong | Copy both again from your BackOffice |
A tool answers ProAbono API error 401, and both keys are right | The endpoint and the keys come from two different accounts | Take all seven variables from the same account |
Building from source
The published package is self-contained: the ProAbono API contract and documentation are copied into dist/resources/ at build time, so nothing is fetched at run time.
A clone builds the same way, with no credential and no access to anything of ours:
npm ci && npm run build && npm test
Both sources the build vendors live in this repository, under resources/: the API Live contract in resources/open-api/ and the documentation corpus in resources/docs/. The contract is a copy of the one ProAbono maintains internally. npm run build and npm test refresh it from there when that source is reachable, and use the committed copy when it is not — which is the case in CI and in any clone of this repository — and say which on every run. See resources/open-api/index.md.
Support
Issues and questions: mcp@proabono.com.
When reporting a problem, include the output of get_server_info — it reports the server version and which variables are configured, and never their values.
Beyond this server:
Licence
MIT. See LICENSE.