Tools reference
The 20 tools exposed by the RedERP MCP server: inputs, outputs, annotations and typical workflows for clients, products, sales documents, payments and KPIs.
All tools run as the connected user through the regular RedERP API: company scoping, role permissions and branch restrictions apply exactly as in the web app. Each tool declares MCP annotations — every tool is openWorldHint: false and destructiveHint: false; write tools are additive only.
Document types used by the *_sales_document* tools: quotation, sales_order, delivery_note, invoice, credit_note, return_note.
Discovery
| Tool | Read-only | Description |
|---|---|---|
search | yes | Free-text search across clients, products and all sales document types. Returns typed ids (invoice:<uuid>), titles, links and a snippet. |
fetch | yes | Full record for a typed id from search (documents include lines, payments and the PDF link). |
Clients
| Tool | Read-only | Inputs | Returns |
|---|---|---|---|
list_clients | yes | search, page, limit | Clients with contact details, credit terms and outstanding balance |
get_client | yes | client_id | Profile, addresses, financial summary (invoiced, paid, outstanding, credit) |
create_client | no | name (required), email, phone, tax number, address, business type, payment terms, credit limit, notes | The new client (names are unique per company) |
get_client_statement | yes | client_id, date_from, date_to | Chronological statement lines (debit / credit) and totals with the balance |
Products & setup
| Tool | Read-only | Inputs | Returns |
|---|---|---|---|
list_products | yes | search, stock_status (in_stock / low_stock / out_of_stock), page, limit | Products with price, VAT and total stock |
get_product | yes | product_id | Product details, variants and available stock per warehouse |
get_sales_setup_options | yes | — | Locations / warehouses, ledgers, payment methods, VAT rates, branches (ids needed to create documents) |
Sales documents
| Tool | Read-only | Inputs | Returns |
|---|---|---|---|
list_sales_documents | yes | document_type, status, payment_status (invoices), client_id, search, date_from, date_to, all_years, page, limit | Documents with status, client, totals, pdf_url, print_url, app_url |
get_sales_document | yes | document_type, id | Header, client, lines, linked documents, payments, links |
get_sales_document_pdf | yes | document_type, id | Time-limited PDF download link, filename, print and app links |
create_sales_document | no | document_type, client_id, date, due_or_expiry_date, location_id, ledger_id, note, items[] (product_id, quantity, unit_price, tax_rate, discount_percentage) | The new draft document with lines and links. Missing location / ledger fall back to the company default |
add_sales_document_items | no | document_type, id, items[] | Updated document (existing lines are never modified) |
update_sales_document_status | no | document_type, id, status | Document after a forward-only status change |
convert_sales_document | no | source_type, source_id, target_type, reason | The new document, linked to its source |
Allowed status transitions
| Document | Statuses accepted by update_sales_document_status |
|---|---|
| quotation | sent, accepted |
| sales_order | confirmed, in-production, ready, shipped, delivered, completed |
| delivery_note | sent, confirmed, shipped |
| invoice | sent, approved |
| credit_note | issued, sent, acknowledged |
| return_note | received, acknowledged, approved, completed |
cancelled, voided, rejected and void are refused — use the RedERP web app for those.
Allowed conversions
| From | To |
|---|---|
| quotation | sales_order, invoice, delivery_note |
| sales_order | invoice, delivery_note |
| delivery_note | invoice |
| invoice | delivery_note, credit_note |
| return_note | credit_note |
Payments
| Tool | Read-only | Inputs | Returns |
|---|---|---|---|
list_payments | yes | client_id, status, date_from, date_to, search, page, limit | Payments with method, date, amount and invoice allocations |
get_payment | yes | payment_id | One payment with allocations |
record_payment | no | client_id, amount, paid_at, payment_method_id, ledger_id, invoice_id or allocations[], reference, note | The recorded payment and the updated invoices (remaining balance, PDF link) |
Reporting
| Tool | Read-only | Inputs | Returns |
|---|---|---|---|
get_sales_dashboard | yes | date_from, date_to, include_monthly_series | Invoiced total, unpaid invoices, quotations and conversion rate, orders, pending deliveries, latest documents, optional monthly series |
Typical workflows
Quote to cash
list_clients → list_products → create_sales_document (quotation with items) → update_sales_document_status (sent) → convert_sales_document (→ sales_order) → convert_sales_document (→ invoice) → record_payment.
Send a document
list_sales_documents or search to find it → get_sales_document_pdf → share pdf_url with the customer (link expires after 7 days).
Follow receivables
list_sales_documents (document_type: invoice, payment_status: pending) → get_client_statement for a given client → record_payment when money arrives.
Fiscal year default:
Like the web app, lists default to the company's current fiscal year. Pass all_years: true or a date range to include older documents; search always spans all years.