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 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.
Installs ProAbono into a website from the IDE: hosted pages, rights sync, catalogue, billing.
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
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."
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.
Tools
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.
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.