MCP Tools Reference
The PayRequest Billing Server provides four tools for managing invoices through AI assistants.get-invoice-stats
Get aggregated statistics about your invoices including totals, pending amounts, and overdue counts.Parameters
This tool takes no parameters.Example Usage
“What are my invoice statistics?”
Response
Response Fields
| Field | Type | Description |
|---|---|---|
total_invoices | integer | Total number of invoices |
pending_invoices | integer | Invoices awaiting payment |
paid_invoices | integer | Fully paid invoices |
overdue_invoices | integer | Invoices past due date |
total_outstanding | decimal | Sum of all unpaid invoices (EUR) |
total_overdue | decimal | Sum of overdue invoices (EUR) |
list-invoices
List invoices with optional filtering by status. Returns invoice details including customer information, amounts, and dates.Parameters
Filter by invoice status. Options:
pending- Includes pending, sent, and viewed invoicespaid- Only paid invoicescanceled- Only canceled invoicesrefunded- Only refunded invoices
Maximum number of invoices to return (1-100)
Example Usage
“Show me all pending invoices”
“List my last 10 paid invoices”
Response
get-overdue-invoices
Get a list of all overdue invoices with customer details, amounts, and days overdue. Sorted by due date (oldest first).Parameters
Maximum number of overdue invoices to return (1-100)
Example Usage
“Which invoices are overdue?”
“Show me the 5 most overdue invoices”
Response
Use Cases
Daily billing review
Daily billing review
Ask: “What invoices are overdue?” to start your day with a clear picture of outstanding payments.
Priority follow-up
Priority follow-up
Ask: “Show me the 5 most overdue invoices” to focus on the oldest unpaid invoices first.
Revenue recovery
Revenue recovery
Ask: “How much revenue is tied up in overdue invoices?” to understand your cash flow impact.
send-invoice-reminder
Send a payment reminder email for a specific invoice. The reminder is sent to the customer’s email address and logged in your activity history.Parameters
The ID of the invoice to send a reminder for
The invoice number (e.g., “INV-2025-042”) to send a reminder for
Provide either
invoice_id OR invoice_number, not both.Example Usage
“Send a reminder for invoice INV-2025-042”
“Remind the customer about invoice 1234”
Response
Validation
The tool validates before sending:| Check | Error Message |
|---|---|
| Invoice not found | ”Invoice not found or does not belong to your account.” |
| Already paid | ”Invoice #X is already paid. No reminder needed.” |
| Canceled | ”Invoice #X is canceled. Cannot send reminder.” |
| No customer email | ”Invoice #X has no customer email address.” |
Activity Logging
Each reminder sent via MCP is logged with:- Timestamp
- Customer email
- Days overdue at time of sending
- Source marked as “MCP API”
Error Handling
All tools return errors in a consistent format:Common Errors
| Error | Cause | Solution |
|---|---|---|
| ”Authentication required” | Missing or invalid token | Check your API token configuration |
| ”Invoice not found” | Invalid ID or wrong account | Verify the invoice ID/number |
| ”Already paid” | Invoice status is ‘paid’ | No action needed |