Refrens MCP
Documentation

Connect Refrens MCP to Claude and ChatGPT

Add the hosted MCP endpoint, complete the Refrens OAuth screen, choose the scopes your AI workspace should use, and start using Refrens tools without manually handling bearer tokens.

OAuth connectorSetup Flow
  1. Add the Refrens MCP endpoint in your AI client: https://refrens-mcp.vercel.app/api/mcp.
  2. Let the client discover the OAuth metadata and open the Refrens authorization page.
  3. Enter the Refrens business URL key and App ID from Refrens Settings > Integrations.
  4. Authenticate with either an app secret or a PEM private key.
  5. Select the minimum scopes needed and click Authorize to return to the AI client.
custom connectorClaude

Add Refrens MCP from Claude's connector settings.

  1. Open Claude Settings and go to Connectors.
  2. Choose Add custom connector.
  3. Use Refrens MCP as the name.
  4. Use https://refrens-mcp.vercel.app/api/mcp as the remote MCP server URL.
  5. Leave OAuth Client ID and OAuth Client Secret blank unless your workspace requires a pre-registered OAuth client.
  6. Click Add or Connect, complete the Refrens authorization page, and approve the connector if your Claude workspace requires admin approval.

If Claude says a server with this URL already exists, remove the older custom connector or reconnect the existing Refrens MCP entry.

custom connectorChatGPT

Add Refrens MCP from ChatGPT's connector or app settings.

  1. Open ChatGPT Settings and go to Connectors or Apps.
  2. Create a custom MCP connector for your workspace.
  3. Use Refrens MCP as the connector name.
  4. Use https://refrens-mcp.vercel.app/api/mcp as the MCP server URL.
  5. Allow ChatGPT to use OAuth discovery and dynamic client registration if those options are shown.
  6. Complete the Refrens authorization page, choose scopes, and return to ChatGPT.

Once connected, test with: Run Refrens health_check and list my latest 5 invoices.

access modelScopes
business:read

Read safe business profile and context.

inventory:read

Read inventory items, batches, stock status, and inventory shortcuts.

transactions:read

Read stock transactions within supported date windows.

inventory:write

Create inventory items.

transactions:write

Adjust or transfer stock.

invoices:read

Read invoices, invoice payments, aging, and receivables helpers.

expenditures:read

Read expenditures, vendor bills, payment status, and line items.

invoices:create

Create invoices using the safe v1 invoice subset.

quotations:create

Create quotations/estimates.

proformas:create

Create proforma invoices.

purchaseorders:create

Create purchase orders.

salesorders:create

Create sales orders.

deliverychallans:create

Create delivery challans.

expenditures:create

Create expenses and purchases.

invoice-payments:write

Record invoice payments.

invoices:cancel

Cancel invoices.

invoices:irn

Generate IRN/e-invoice details for existing invoices.

66 toolsTool Catalog

This catalog is adapted from docs/mcp-tools.md. MCP clients should not ask users for businessId; the hosted bearer token selects the business.

Setup and business context

Use these first to confirm the connector and identify the connected business.

2 tools
health_checknone

Checks whether the MCP server is reachable and Refrens credentials are configured.

Run Refrens health_check.
get_business_basic_contextbusiness:read

Returns safe business context for the connected Refrens business.

Which Refrens business is this MCP connected to?

Inventory reads

Read inventory items, batches, tracking, stock state, and business-friendly shortcuts.

4 tools
list_inventory_itemsinventory:read

Generic inventory list with filters for name, item type, tracking method, stock management, and stock status.

Show my first 10 inventory items.
get_inventory_item_by_skuinventory:read

Fetches one inventory item by SKU.

Get inventory item SKU-1001.
list_inventory_batchesinventory:read

Lists batches for an inventory item by SKU, with optional batch code or name filters.

List batches for SKU-1001.
get_inventory_tracking_method_breakdowninventory:read

Counts inventory grouped by BATCH, SERIAL, NONE, and unspecified/other tracking methods.

Show inventory count by tracking method.

Inventory shortcuts

Read-only aliases over inventory list filters so clients do not guess enum values.

10 tools
list_low_stock_itemsinventory:read

Lists inventory with low stock status.

list_critical_stock_itemsinventory:read

Lists inventory with critical stock status.

list_overstock_itemsinventory:read

Lists overstocked inventory.

list_well_stocked_itemsinventory:read

Lists well-stocked inventory.

list_productsinventory:read

Lists product inventory items.

list_servicesinventory:read

Lists service inventory items.

list_batch_tracked_itemsinventory:read

Lists batch-tracked items.

list_serial_tracked_itemsinventory:read

Lists serial-tracked items.

list_untracked_itemsinventory:read

Lists items with NONE tracking method.

list_stock_managed_itemsinventory:read

Lists stock-managed inventory.

Inventory writes and transactions

Create items and inspect or mutate stock transactions. Mutation tools require explicit write scopes.

9 tools
create_inventory_iteminventory:write

Creates a new inventory item. Warehouse-managed businesses should pass warehouse codes such as WH0001.

Create a stock-managed item called USB Cable with opening stock 10 in WH0001.
list_inventory_transactionstransactions:read

Lists transactions for one SKU. Dates are optional, default to the last 30 days, and may span at most 31 days.

Show stock transactions for SKU-1001 from 2026-05-01 to 2026-05-15.
list_stock_in_transactionstransactions:read

Shortcut for list_inventory_transactions filtered to BUY stock receipts.

list_stock_out_transactionstransactions:read

Shortcut for list_inventory_transactions filtered to SELL stock issues.

list_stock_affecting_transactionstransactions:read

Shortcut for list_inventory_transactions filtered to transactionType=UPDATE.

list_blocked_stock_transactionstransactions:read

Shortcut for list_inventory_transactions filtered to transactionType=BLOCK.

list_unmanaged_stock_transactionstransactions:read

Shortcut for list_inventory_transactions filtered to transactionType=IGNORE.

adjust_inventory_stocktransactions:write

Records a manual BUY or SELL stock adjustment. MCP clients should treat this as destructive.

transfer_inventory_stocktransactions:write

Transfers stock between warehouses using warehouse codes. MCP clients should treat this as destructive.

Invoice reads and shortcuts

Read invoices, find invoices, and answer common receivables questions.

15 tools
list_invoicesinvoices:read

Lists invoices with pagination, status, e-invoice generated status, supply type, invoice number, client, invoice-date, due-date, sort filters, and optional share links.

Show my latest 10 Refrens invoices.
get_invoice_by_idinvoices:read

Fetches one invoice by the internal invoice ID returned by list or find tools.

find_invoice_by_numberinvoices:read

Finds invoices by business-facing invoice number, including share link and PDF URL by default.

Find invoice INV-001.
list_overdue_invoicesinvoices:read

Lists overdue invoice documents; use get_invoice_aging_summary for aging buckets.

list_unpaid_invoicesinvoices:read

Shortcut for unpaid invoices.

list_partially_paid_invoicesinvoices:read

Shortcut for partial invoices.

list_paid_invoicesinvoices:read

Shortcut for paid invoices.

list_due_soon_invoicesinvoices:read

Lists outstanding invoices due in the next N days.

list_recent_invoicesinvoices:read

Lists recent invoices, newest first by invoice date or created date.

list_high_value_unpaid_invoicesinvoices:read

Combines unpaid and partial invoices, sorted by due amount.

list_invoices_by_einvoice_statusinvoices:read

Shortcut for e-invoice generated status filters such as ACTIVE, NOT_GENERATED, and ERROR.

list_invoices_by_supply_typeinvoices:read

Shortcut for GST supply type filters such as B2B, SEZWP, SEZWOP, EXPWP, EXPWOP, DEX, and B2C.

find_invoices_to_generate_irninvoices:read

Finds compact India invoice candidates for IRN generation, defaulting invoice date to last month and filtering failed/not-generated e-invoice status plus supported supply types.

list_invoices_by_clientinvoices:read

Lists invoices for a client ID with optional filters.

list_overdue_invoices_by_clientinvoices:read

Lists overdue invoices for a client ID.

Invoice analysis and payments

Summaries and payment helpers that turn invoice documents into compact business answers.

13 tools
list_invoice_paymentsinvoices:read

Lists payments recorded against one invoice ID.

get_invoice_payment_statusinvoices:read

Returns paid amount, due amount, outstanding flag, overdue flag, and last payment.

list_recent_invoice_paymentsinvoices:read

Finds recent payments visible in the newest invoice window; older-invoice payments can be missed.

get_invoice_aging_summaryinvoices:read

Groups overdue invoices into aging buckets.

get_receivables_summaryinvoices:read

Summarizes unpaid, partial, and overdue receivables by currency.

get_daily_business_digestinvoices:read + inventory:read

Builds a schedule-friendly digest covering receivables, overdue invoices, invoices due soon, and low or critical stock alerts.

Run my Refrens daily business digest.
get_client_invoice_summaryinvoices:read

Summarizes receivables and recent invoices for one client.

find_invoiceinvoices:read

Flexible invoice search by number, client id or name, status, e-invoice generated status, supply type, and date range, including share link and PDF URL by default.

get_invoice_line_itemsinvoices:read

Returns focused line-item details for one invoice.

create_invoiceinvoices:create

Creates an invoice using the safe v1 invoice subset. Email sending is not exposed.

record_invoice_paymentinvoice-payments:write

Records a payment against an invoice. MCP clients should treat this as destructive.

cancel_invoiceinvoices:cancel

Cancels an invoice by setting status to CANCELED. MCP clients should treat this as destructive.

generate_invoice_irninvoices:irn

Generates IRN/e-invoice details for an existing invoice using the business e-invoice configuration.

Sales document writes

Create customer and vendor-facing documents using the same safe v1 document subset as invoices.

5 tools
create_quotationquotations:create

Creates a quotation/estimate. The quotation number is assigned from the business series.

create_proformaproformas:create

Creates a proforma invoice and sets billType to PROFORMAINV.

create_purchaseorderpurchaseorders:create

Creates a purchase order and sets billType to PURCHASEORDER.

create_deliverychallandeliverychallans:create

Creates a delivery challan and sets billType to DELIVERYCHALLAN.

create_salesordersalesorders:create

Creates a sales order with customer, item, shipping, term, and reminder details.

Expenditure reads and writes

Read vendor bills, find expenditure PDFs, inspect payment or line-item details, and create expenses or purchases.

8 tools
list_expendituresexpenditures:read

Lists expenditures with pagination, status, expense number, vendor-name, date, sort filters, optional share links, and derived purchase/petty-expense kind.

Show recent vendor bills.
get_expenditure_by_idexpenditures:read

Fetches one expenditure by the internal expenditure ID returned by list or find tools.

find_expenditure_by_numberexpenditures:read

Finds expenditures by business-facing expense number, including share link and PDF URL by default.

Find expenditure EXP-001.
find_expenditureexpenditures:read

Flexible expenditure search by number, vendor name, status, invoice date, and due date.

get_expenditure_payment_statusexpenditures:read

Returns paid amount, due amount, outstanding flag, overdue flag, and last payment.

get_expenditure_line_itemsexpenditures:read

Returns focused line-item details for one expenditure.

create_expenseexpenditures:create

Creates a petty expense or vendor expense. Currency is required and not inferred.

create_purchaseexpenditures:create

Creates a purchase/vendor expenditure with supplier, line item, due-date, term, and reminder details.

Current gaps: serial-number detail tools, warehouse read tools, invoice email sending, e-waybill/LHDN/ZATCA, credit-note routes, invoice reports, and payment removal or approval patching are outside the v1 surface.
expiryToken Refresh

OAuth clients receive scoped access and refresh tokens from the hosted connector. If a user revokes the connector or changes requested scopes, reconnect from the AI client.

App-secret authentication uses the upstream Refrens bearer token created during authorization. Private-key authentication stores the encrypted private key and refreshes Refrens bearer tokens automatically when the bearer reaches 70% of its JWT lifetime, is expired, undecodable, or rejected by Refrens with a 401 during a tool call.

reviewedSecurity
  • Raw customer-facing MCP bearer tokens are never stored; only SHA-256 hashes are persisted.
  • Persistent stores require encrypted Refrens bearers and private keys via MCP_TOKEN_ENCRYPTION_KEY.
  • App secrets are not stored, and automatic refresh is limited to private-key setup.
  • Usage events do not store request bodies, response bodies, app secrets, MCP bearers, or Refrens bearers.
  • Dependency audit is clean after patched transitive updates and a PostCSS override.
The detailed review lives in docs/security-review.md in the repository. Production should still move storage and audit logs to internal Refrens infrastructure.