REST API Docs | MCP Tool Reference 29 tools

MCP Tool Reference

The Greenstamp MCP (Model Context Protocol) server exposes structured tools for agents and AI assistants to interact with invoices, bills, payments, bank reconciliation, and more.

Endpoint: POST /mcp (JSON-RPC 2.0 over HTTP)

Authentication: Include a copilot-type API key as a Bearer token:

Authorization: Bearer <your-api-key>

API keys are created in Settings → API Keys. Only keys with the copilot type can access the MCP endpoint.

Tool discovery: Send a tools/list JSON-RPC call to retrieve the live tool schema. The tools documented here exactly match what the server returns from tools/list.

Tool Index

Search - search

Entities - list_entities

Counterparties - list_counterparties - create_counterparty

Invoices - search_invoices - get_invoice - create_invoice

Bills (Accounts Payable) - search_bills - get_bill - create_bill

Payments - record_invoice_payment - record_bill_payment - get_payment_summary

Tasks - list_tasks - create_task - complete_task

Bank Reconciliation - list_bank_accounts - get_bank_account - update_bank_account - set_bank_account_active - list_bank_statements - search_bank_transactions - run_ai_matching - confirm_bank_match - reject_ai_suggestion - link_transfer

Ledgers - generate_ledger

Exports - export_invoices - export_bills

Search across all record types: invoices, customers, bills, bill tickets, clients, tasks, and more. Returns results ranked by relevance. Use this for quick lookups by name, number, or identifier.

Parameters:

Parameter Type Required Description
query string Yes Search term (minimum 2 characters). Matches names, identifiers, folio numbers, RFC, etc.
types string[] (invoices, counterparties, entities, clients, team_members, invoice_payments, invoice_credit_notes, invoicing_arrangements, bills, bill_payments, bill_credit_notes, products, ledger_accounts, tasks, bill_tickets) No Optional: limit search to specific types. Available: invoices, counterparties, entities, clients, team_members, invoice_payments, invoice_credit_notes, invoicing_arrangements, bills, bill_payments, bill_credit_notes, products, ledger_accounts, tasks, bill_tickets

Entities

list_entities

List all entities (empresas/razones sociales) accessible to this API key. Use this to discover available entities before calling entity-scoped tools. Entity-scoped API keys will only see their bound entity. Organization-scoped keys see all entities in the organization.

No input parameters.


Counterparties

list_counterparties

Search and list counterparties (customers/suppliers) for the current entity. Use this to find a counterparty before creating an invoice. Supports search by name or RFC (Mexican tax ID).

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
query string No Search by name or RFC (tax ID). Case-insensitive partial match.
role string (customer, supplier, all) No Filter by role. Default: 'customer'.
limit integer No Max results (default: 20, max: 50).

create_counterparty

Create a new counterparty (customer or supplier) for the current entity. For Mexico, RFC and fiscal regime are required for invoicing. Uses the CounterpartyForm for full validation including RFC format, fiscal regime, and duplicate detection.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
name string Yes Legal name of the counterparty.
country_code string No ISO country code (default: entity's country). Common: MX, US, PL, PE.
country_details object No Country-specific counterparty fields keyed by country_code. For MX: rfc, fiscal_regime_code, cfdi_use_code.
email string No Contact email.
postal_code string No Postal code (required for Mexico).
is_customer boolean No Mark as customer (default: true). Required for invoicing.
is_supplier boolean No Mark as supplier (default: false).

country_details fields:

Parameter Type Required Description
rfc string No For MX: Mexican RFC (tax ID). Required for Mexican counterparties. Example: 'XAXX010101000' for generic public.
fiscal_regime_code string No For MX: SAT fiscal regime code. Common: '601' (General), '612' (Persona Física), '616' (No fiscal obligations).
cfdi_use_code string No For MX: Default CFDI use. Default: 'G03' (general expenses). Use 'S01' for generic RFC.

Invoices

search_invoices

Search for invoices (facturas) with various filters. Can filter by customer name, status, date range, and more. Supports virtual statuses: overdue (filed + past due), pending (filed + not yet due), stale_draft (draft > 3 days old). Returns a paginated list of matching invoices.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
query string No Search by customer name, invoice title, folio number, or RFC.
status string (draft, stale_draft, filed, overdue, pending, paid, partially_paid, unpaid, void, reversed) No Filter by status. Includes virtual statuses: overdue, pending, stale_draft, paid, unpaid, partially_paid.
date_from string No Start date for issue date filter (YYYY-MM-DD).
date_to string No End date for issue date filter (YYYY-MM-DD).
counterparty_id string No Filter by customer/counterparty public identifier.
limit integer No Max results (default: 10, max: 50).

get_invoice

Get full details of an invoice by its ID, including line items, filing/stamping status, and payment information.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
invoice_id string Yes Invoice public identifier (e.g., 'invc_xxxxx').

create_invoice

Create a new draft invoice for an entity. The invoice is created in draft status and must be separately submitted for fiscal stamping via submit_invoice.

IMPORTANT WORKFLOW: Always create as draft first, then let the user review before stamping. Stamping is irreversible.

COUNTERPARTY RESOLUTION: - Provide counterparty_id (public_identifier) if known, OR counterparty_name for fuzzy matching - If counterparty_name matches multiple results, the tool returns suggestions — ask the user to clarify - The counterparty must already exist and be marked as a customer (is_customer: true) - If no match found, suggest using create_counterparty first

COUNTRY-SPECIFIC FIELDS (country_details): Pass country_details with fields appropriate to the entity's fiscal regime. For MX (country_code: MX) — CFDI invoice (factura): - payment_method: "PUE" (single payment, default) or "PPD" (installments/deferred) - payment_form: "03" (wire transfer, default). Common: "01" cash, "04" card, "99" TBD - cfdi_use: "G03" (general expenses, default). Must be "S01" for generic RFC XAXX010101000 - cfdi_type: Always "I" (Ingreso) for regular invoices.

LINE ITEMS: - Each needs: description, unit_price (before tax). quantity defaults to 1. - For MX: pass country_details per line item with sat_product_code and sat_unit_code. - sat_product_code: 8-digit SAT code. Common: 80101501=consulting, 84111506=software, 43231500=licenses - sat_unit_code: Default "E48" (service). Common: "H87"=piece, "HUR"=hour, "MON"=month - IVA 16% calculated automatically. Do NOT include tax in unit_price.

TIPS FOR NATURAL LANGUAGE CONVERSION (MX): - "40 horas a $125" → quantity: 40, unit_price: 125.00, country_details: { sat_unit_code: "HUR" } - "servicios del mes de enero" → quantity: 1, country_details: { sat_unit_code: "MON" } - "$5,800 con IVA" → back-calculate: unit_price = 5800 / 1.16 = 5000

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
counterparty_id string No Counterparty public identifier. Use this if you know the exact ID.
counterparty_name string No Customer name for fuzzy matching. Used when counterparty_id is not known.
title string No Invoice title/description (e.g., 'Servicios profesionales enero 2025').
currency string No Currency code (default: 'MXN'). For USD/EUR, exchange rate is auto-fetched.
country_details object No Country-specific invoice fields keyed by the entity's fiscal regime. For MX: payment_method, payment_form, cfdi_use.
line_items object[] Yes Invoice line items. At least one required.
payment_terms_days integer No Days until due. Default: 0 for PUE, 30 for PPD.
notes string No Invoice observations/notes.

country_details fields:

Parameter Type Required Description
payment_method string (PUE, PPD) No For MX: payment method. PUE=single payment (default), PPD=installments/deferred.
payment_form string No For MX: payment form code. Default: '03' (wire transfer). Common: '01' cash, '04' card, '99' TBD.
cfdi_use string No For MX: CFDI use code. Default: 'G03' (general expenses). Must be 'S01' for generic RFC.

line_items[] fields:

Parameter Type Required Description
description string Yes Product or service description.
quantity number No Quantity (default: 1).
unit_price number Yes Unit price BEFORE tax.
country_details object No Country-specific line item fields. For MX: sat_product_code, sat_unit_code.

line_items[].country_details fields:

Parameter Type Required Description
sat_product_code string No For MX: 8-digit SAT product code (default: '80101501' consulting).
sat_unit_code string No For MX: SAT unit code (default: 'E48' service).

Bills (Accounts Payable)

search_bills

Search for bills (supplier invoices / cuentas por pagar) with various filters. Can filter by vendor name, status, payment status, deductibility, and date range. Returns a paginated list of matching bills.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
query string No Search by vendor/supplier name or bill number.
status string (inbox, received, validated, rejected, reversed) No Filter by bill status.
payment_status string (unpaid, partially_paid, paid, overpaid) No Filter by payment status.
deductibility string (deductible, non_deductible, partially_deductible, pending_review) No Filter by deductibility status (Mexico).
date_from string No Start date for issue date filter (YYYY-MM-DD).
date_to string No End date for issue date filter (YYYY-MM-DD).
overdue_only boolean No If true, only return overdue bills.
limit integer No Max results (default: 10, max: 50).

get_bill

Get full details of a bill (supplier invoice) by its ID, including line items, filing/validation status, payment information, and deductibility.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
bill_id string Yes Bill public identifier (e.g., 'bill_xxxxx').

create_bill

Create a new bill (supplier invoice received) for the entity. The bill is created in 'received' status.

COUNTERPARTY RESOLUTION: - Provide counterparty_id (public_identifier) if known, OR counterparty_name for fuzzy matching - If counterparty_name matches multiple results, the tool returns suggestions — ask the user to clarify - The counterparty must already exist and be marked as a supplier (is_supplier: true) - If no match found, suggest using create_counterparty first

LINE ITEMS: - Each needs: description, unit_price. quantity defaults to 1. - tax_amount is optional (defaults to 0).

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
counterparty_id string No Counterparty public identifier. Use this if you know the exact supplier ID.
counterparty_name string No Supplier name for fuzzy matching. Used when counterparty_id is not known.
bill_number string Yes Bill/invoice number from the supplier.
series string No Bill series prefix (e.g., 'A', 'FAC').
title string No Bill title/description.
issue_date string No Bill issue date (YYYY-MM-DD). Defaults to today.
due_date string No Payment due date (YYYY-MM-DD). Defaults to issue_date + 30 days.
currency string No Currency code (default: 'MXN').
line_items object[] Yes Bill line items. At least one required.
notes string No Internal notes for this bill.

line_items[] fields:

Parameter Type Required Description
description string Yes Item description.
quantity number No Quantity (default: 1).
unit_price number Yes Unit price.
tax_amount number No Tax amount for this line (default: 0).

Payments

record_invoice_payment

Record a customer payment received on an invoice (cobro de factura). Creates a payment record and automatically allocates it to the specified invoice. If amount is omitted, pays the full balance due.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
invoice_id string Yes Invoice public identifier (e.g., 'invc_xxxxx') to apply payment to.
amount number No Payment amount. If omitted, pays the full balance due.
currency string No Currency code (default: invoice currency).
payment_date string No Payment date (YYYY-MM-DD). Defaults to today.
payment_method string (cash, check, wire_transfer, credit_card, debit_card, other) No Payment method (default: 'wire_transfer').
reference_number string No Payment reference number.
notes string No Payment notes.

record_bill_payment

Record a payment made to a supplier on a bill (pago a proveedor). Creates a payment record and automatically allocates it to the specified bill. Use payment_mode 'full' to automatically pay the full amount due, or provide a specific amount for partial payments.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
bill_id string Yes Bill public identifier (e.g., 'bill_xxxxx') to apply payment to.
amount number No Payment amount. Omit to pay the full balance.
currency string No Currency code (default: bill currency).
paid_on string No Payment date (YYYY-MM-DD). Defaults to today.
payment_method string (transfer, check, cash, card, other) No Payment method (default: 'transfer').
reference string No Payment reference.
notes string No Payment notes.

get_payment_summary

Get a summary of accounts receivable (AR) and accounts payable (AP) for an entity. Shows outstanding amounts, overdue items, and recent payment activity. Useful for a quick financial health overview.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.

Tasks

list_tasks

List tasks (to-dos / action items) for the entity. Can filter by status, priority, assignee, and related document type. Returns open tasks by default, ordered by priority then due date.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
status string (open, pending, in_progress, completed, cancelled) No Filter by status. 'open' includes both pending and in_progress. Default: 'open'.
priority string (urgent, high, normal, low) No Filter by priority level.
taskable_type string (Invoice, Bill, InvoiceCreditNote, InvoicePayment, BillTicket, Counterparty, Entity) No Filter by the type of document the task is attached to.
overdue_only boolean No If true, only return overdue tasks.
limit integer No Max results (default: 20, max: 50).

create_task

Create a new task (action item / to-do) on a document or counterparty. Tasks can be assigned to team members and have due dates and priorities.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
title string Yes Task title (what needs to be done).
description string No Detailed task description.
priority string (urgent, high, normal, low) No Task priority (default: 'normal').
due_at string No Due date/time (ISO 8601, e.g., '2025-02-15' or '2025-02-15T17:00:00Z').
assigned_to_email string No Email of the user to assign this task to. Must be a member of the organization.
taskable_type string (Invoice, Bill, InvoiceCreditNote, InvoicePayment, BillTicket, Counterparty, Entity) Yes Type of document to attach the task to.
taskable_id string Yes Public identifier of the document (e.g., 'invc_xxxxx', 'bill_xxxxx').

complete_task

Mark a task as completed. The task must be in an open state (pending or in_progress).

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
task_id string Yes Task public identifier (e.g., 'task_xxxxx').

Bank Reconciliation

list_bank_accounts

List bank accounts for the entity with reconciliation statistics. Shows unmatched and suggested match counts to help prioritize reconciliation work.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.

get_bank_account

Get detailed info for a single bank account: identifiers, status, reconciliation stats, and jurisdiction-specific fields (CLABE / routing number / IBAN+BIC).

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
bank_account_id string Yes Bank account public identifier (e.g., 'bacc_xxxxx').

update_bank_account

Update a bank account's name, account type, masked account number, currency, or jurisdiction-specific identifier (CLABE for MX, routing number for US, IBAN/BIC for PEPPOL). Only the fields you provide are touched.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
bank_account_id string Yes Bank account public identifier (e.g., 'bacc_xxxxx').
name string No Friendly account name.
account_number_masked string No Last 4 digits of the account number (4-digit string).
account_type string (checking, savings, credit) No Account type.
currency string No ISO 4217 3-letter currency code.
clabe string No 18-digit CLABE (Mexico only; ignored otherwise).
routing_number string No 9-digit routing number (US only; ignored otherwise).
iban string No IBAN (PEPPOL countries only; ignored otherwise).
bic string No BIC/SWIFT code (PEPPOL countries only; ignored otherwise).

set_bank_account_active

Activate or deactivate a bank account. Deactivated accounts are hidden from reconciliation but their history is preserved.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
bank_account_id string Yes Bank account public identifier (e.g., 'bacc_xxxxx').
active boolean Yes true to reactivate, false to deactivate.

list_bank_statements

List imported bank statements for an entity, optionally filtered to one bank account. Each statement represents one CSV import and holds its transactions.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
bank_account_id string No Bank account public identifier to filter by (e.g., 'bacc_xxxxx').
limit integer No Max results (default: 25, max: 100).

search_bank_transactions

Search and filter bank transactions for reconciliation. Can filter by bank account, match status, transaction type, date range, amount range, and description text.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
bank_account_id string No Bank account public identifier to filter by.
match_status string (unmatched, suggested, confirmed, no_match) No Filter by reconciliation status.
transaction_type string (credit, debit) No Filter by type (credit = money in, debit = money out).
date_from string No Start date filter (YYYY-MM-DD).
date_to string No End date filter (YYYY-MM-DD).
amount_min number No Minimum transaction amount.
amount_max number No Maximum transaction amount.
query string No Search in transaction description and reference.
limit integer No Max results (default: 20, max: 50).

run_ai_matching

Run AI matching across all unmatched transactions on a bank account. High-confidence matches (≥90%) are auto-confirmed; medium-confidence (70–89%) become suggestions. Idempotent: re-running on the same transaction set within 5 minutes returns the prior result.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
bank_account_id string Yes Bank account public identifier (e.g., 'bacc_xxxxx').

confirm_bank_match

Confirm a match between a bank transaction and one or more invoices/bills. Creates a single payment record (with N allocations) by default.

Two shapes are supported:

  1. Single match — pass matched_record_id; the full transaction amount is allocated to that record.

  2. Split — pass allocations: [{matched_record_id, amount}, ...] to allocate the transaction across multiple invoices/bills. All allocations must share the same record type (Invoice|Bill), counterparty, and currency. Amounts are in major units (e.g., dollars) and must sum to the transaction amount.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
transaction_id string Yes Bank transaction public identifier (e.g., 'btxn_xxxxx').
matched_record_id string No Single-match shape: invoice or bill public identifier (e.g., 'invc_xxxxx' or 'bill_xxxxx'). Mutually exclusive with allocations.
allocations object[] No Split shape: list of {matched_record_id, amount} objects. amount is in major units.
create_payment boolean No Whether to automatically create a payment record (default: true).

allocations[] fields:

Parameter Type Required Description
matched_record_id string Yes
amount number Yes

reject_ai_suggestion

Reject the AI-suggested matches on a bank transaction and return it to "unmatched". Use when the suggested invoice/bill is clearly wrong.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
transaction_id string Yes Bank transaction public identifier (e.g., 'btxn_xxxxx').

Link a transaction with its suggested transfer peer on another of your own bank accounts. The pairing comes from internal-transfer detection at import time; this confirms it.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
transaction_id string Yes Bank transaction public identifier (either leg of the transfer).

Ledgers

generate_ledger

Generate an accounts receivable (AR), accounts payable (AP), or combined ledger. Shows chronological entries with running balances for a counterparty or the entire entity. Can optionally return CSV format for export.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
counterparty_id string No Counterparty public identifier to filter ledger entries. If omitted, shows all counterparties.
type string (ar, ap, both) No Ledger type: 'ar' (accounts receivable), 'ap' (accounts payable), or 'both' (default).
date_from string No Start date filter (YYYY-MM-DD).
date_to string No End date filter (YYYY-MM-DD).
format string (json, csv) No Output format: 'json' (default) or 'csv'.

Exports

export_invoices

Export invoices as CSV data. Supports filtering by status, payment status, date range, and counterparty. Returns CSV text that can be saved to a file.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
status string (draft, filed, void, reversed) No Filter by invoice status.
payment_status string (unpaid, partial, paid) No Filter by payment status.
counterparty_id string No Filter by counterparty public identifier.
date_from string No Start date filter on issue_date (YYYY-MM-DD).
date_to string No End date filter on issue_date (YYYY-MM-DD).

export_bills

Export bills (accounts payable) as CSV data. Supports filtering by status, payment status, deductibility, date range, and counterparty. Returns CSV text that can be saved to a file.

Parameters:

Parameter Type Required Description
entity_id string No Entity public identifier. Required for org-scoped API keys.
status string (inbox, received, validated, rejected, reversed) No Filter by bill status.
payment_status string (unpaid, partial, paid) No Filter by payment status.
deductibility string (deductible, non_deductible, pending_review) No Filter by deductibility status.
counterparty_id string No Filter by counterparty (supplier) public identifier.
date_from string No Start date filter on issue_date (YYYY-MM-DD).
date_to string No End date filter on issue_date (YYYY-MM-DD).