POCKET INVOICE MCP

Create invoices
from your AI chat.

Connect once, then describe the work in ordinary language. Your documents are saved in the same account you use on the Web, iOS and Android.

1. Connect Codex

In Codex settings, add an MCP server named Pocket Invoice. Choose Streamable HTTP and use this URL:

https://api.freedominvoice.com/mcp

Choose Authenticate when prompted. Sign in to Pocket Invoice, select one company, review the permissions and choose Allow access. Return to Codex and start a chat with the connection available.

Using the Codex command line

codex mcp add pocket-invoice --url https://api.freedominvoice.com/mcp
codex mcp login pocket-invoice
codex mcp list

In the Codex terminal interface, /mcp shows active connections. codex mcp --help explains connection-management commands.

No Pocket Invoice npm server package is needed: the tools run on the existing Pocket Invoice server. Official Codex MCP setup →

2. Create your first invoice

“Use Pocket Invoice to create an invoice for Joe: 3 tables at 10 each and 5 chairs at 20 each. Generate the PDF.”

The assistant reads your company’s currency and settings, creates one invoice, and generates its PDF. The line amounts are 30 and 100, for a total of 130 in that company’s currency. It uses the saved payment terms unless you give a due date.

Invoice savedJoe · Total 130View invoice · Download PDFExample of the result, not a live invoice.

View invoice opens the matching document’s Preview in the Web list. Sign in if needed; the Web app selects the company that owns the document. Download PDF is a temporary link, valid for one hour by default. Generating an invoice or PDF does not send it.

3. What you can do

Tools are limited by the company, permissions you granted and your team access. Ask in your own words; you do not have to type tool names.

Feature	Try asking
Invoices, estimates & purchase orders	“Create an estimate for Acme: 10 hours at 80.” Create, find, edit, copy and convert documents.
PDFs & attachments	“Generate the PDF for invoice 1042.” Use the saved company logo and template; attach uploaded files.
Send documents	“Prepare invoice 1042 for emailing to the saved customer.” Review recipients and document, confirm, then check the sending result.
Customers	“Find Acme.” Create and edit saved customers, manage tags and reminders, prepare statements and aging reports.
Items & stock	“Show the stock for office chairs.” Create and edit catalog items, adjust inventory and inspect inventory history.
Payments & deposits	“Record a payment of 250 received today for invoice 1042.” These tools record payments; they do not charge a card or transfer money.
Expenses	“Record a 40 transport expense today.” Create and edit expenses and categories, read expense reports and PDFs.
Reports	“Show this month’s sales and outstanding invoices.” Sales, payments, taxes, expenses, profit and loss, and customer reports.
Import & export	“Export my invoices as CSV.” Preview customer or item CSV imports before committing them.
Company & settings	“Show my invoice numbering and PDF settings.” Edit company details, template, labels and tax settings; upload files and mark notifications as read.
Account	“Show my membership information.” Open account settings or subscription pages when a Web action is needed.

Deleting records, managing teams, projects, appointments, schedules and recurring tasks are currently unavailable through MCP. Device operations such as printing and system sharing are outside this connection.

Tool reference: names, descriptions and permissions

add_document_attachmentPermission: documents:write · Required: document_id, url, title, request_id

Attach an uploaded image or file to a document.

adjust_inventoryPermission: items:write · Required: item_id, quantity, note, request_id

Add or subtract stock and record the reason. Use a positive quantity to add stock and a negative quantity to remove it.

cancel_customer_reminderPermission: customers:write · Required: reminder_id, request_id

Cancel a pending customer reminder.

commit_customers_importPermission: customers:write · Required: batch_id, columns, request_id

Create saved customers from a prepared CSV import. Reusing the same batch does not import its rows again.

commit_items_importPermission: items:write · Required: batch_id, columns, request_id

Create saved items from a prepared CSV import. Reusing the same batch does not import its rows again.

convert_to_invoicePermission: documents:write · Required: document_id, request_id

Create an invoice from an estimate or purchase order, preserving the source and linking the conversion.

copy_documentPermission: documents:write · Required: document_id, request_id

Copy an existing document into a new unsent document with a new number. Payment records are not copied.

create_customerPermission: customers:write · Required: name, request_id

Add a customer to the saved customer catalog. Use document customer snapshots when the customer should only appear on one invoice.

create_customer_reminderPermission: customers:write · Required: customer_id, message, remind_at, request_id

Schedule a customer follow-up reminder for the account owner.

create_customer_tagPermission: customers:write · Required: name, color, request_id

Create a tag for organizing saved customers.

create_estimatePermission: documents:write · Required: items, request_id

Create an estimate or quote in the connected company's currency, using the saved template.

create_expensePermission: expenses:write · Required: merchant, amount, date, request_id

Record a business expense; total is calculated from amount, tax and tip.

create_expense_categoryPermission: expenses:write · Required: name, request_id

Add an account-wide expense category. Only the company owner can change shared categories.

create_invoicePermission: documents:write · Required: items, request_id

Create an unsent invoice in the connected account using its company currency and PDF template. Calculates amounts and numbering on the server. Does not send email or add inline customers/items to the saved catalogs.

create_itemPermission: items:write · Required: name, unit_price, request_id

Create an item in the saved catalog, optionally with opening stock.

create_purchase_orderPermission: documents:write · Required: items, request_id

Create a purchase order for the connected company.

create_taxPermission: settings:write · Required: label, inclusive, rates, request_id

Create a saved company tax with named rates.

export_customers_csvPermission: business:read · Required: offset, limit

Export a page of saved customers as a downloadable CSV file.

export_documents_csvPermission: business:read · Required: document_type, offset, limit

Export a page of invoices, estimates or purchase orders as a downloadable CSV file.

export_expenses_csvPermission: business:read · Required: offset, limit

Export a page of company expenses as a downloadable CSV file.

export_items_csvPermission: business:read · Required: offset, limit

Export a page of saved items and stock quantities as a CSV file.

get_account_membershipPermission: business:read · Required: none

Read the signed-in user's account email and subscription information. This does not change a subscription or initiate payment.

get_account_settings_linkPermission: business:read · Required: none

Open account settings to change sign-in details or confirm account deletion in the browser. Account deletion cannot be executed in chat.

get_business_summaryPermission: business:read · Required: none

Read sales, received payments and unpaid balances. Uses the same calculation service as the app, within the connected company and team access.

get_company_settingsPermission: business:read · Required: none

Read the connected company's business details, currency, numbering, payment instructions and PDF template settings.

get_customerPermission: business:read · Required: customer_id

Read a saved customer's details and tags.

get_customer_aging_reportPermission: business:read · Required: none

Read outstanding customer balances by overdue age. Uses the same calculation service as the app, within the connected company and team access.

get_customer_statementPermission: business:read · Required: customer_id

Read an invoice statement for a saved customer, with an optional downloadable CSV. Requires document read access as well as customer read access.

get_detailed_customer_sales_reportPermission: business:read · Required: none

Read detailed customer sales. Uses the same calculation service as the app, within the connected company and team access.

get_documentPermission: business:read · Required: document_id

Read a saved invoice, estimate or purchase order, including its line items, customer snapshot and attachments. Payment records are included only with business:read permission.

get_document_email_historyPermission: business:read · Required: document_id

Read email status history for a saved document.

get_document_pdfPermission: business:read · Required: document_id

Generate a PDF of an existing document with the company's saved logo and template. Returns a download link valid for one hour. Retry this tool with the existing document ID if PDF generation failed after creation.

get_expensePermission: business:read · Required: expense_id

Read an expense and its linked projects.

get_expense_pdfPermission: business:read · Required: expense_id

Generate a PDF for a saved expense.

get_expense_reportPermission: business:read · Required: none

Read expenses as a journal or grouped by category. Uses the same calculation service as the app, within the connected company and team access.

get_file_upload_urlPermission: settings:write · Required: filename, content_type, request_id

Get a temporary upload URL for a logo, attachment or receipt. Upload the file bytes with HTTP PUT, then use file_url in the relevant business tool.

get_helpPermission: business:read · Required: none

Explain how to use Pocket Invoice, list enabled tools for this connection's granted scopes, and provide the setup and user manual links. Use when asked for help, supported features or example invoice requests. Company team permissions still apply to each business action.

get_inventory_historyPermission: business:read · Required: item_id

Read stock movements for a saved item.

get_invoice_overviewPermission: business:read · Required: none

Read the invoice overview and balances. Uses the same calculation service as the app, within the connected company and team access.

get_invoice_reminder_settingsPermission: business:read · Required: none

Read the company owner's account-wide invoice reminder settings. Owner only; these settings apply across their companies.

get_invoices_by_month_reportPermission: business:read · Required: none

Read invoice totals by month. Uses the same calculation service as the app, within the connected company and team access.

get_itemPermission: business:read · Required: item_id

Read a saved item and its stock settings.

get_payment_reportPermission: business:read · Required: none

Read the payment journal or grouped payment breakdown. Uses the same calculation service as the app, within the connected company and team access.

get_payments_by_customer_reportPermission: business:read · Required: none

Read payments grouped by customer. Uses the same calculation service as the app, within the connected company and team access.

get_payments_by_date_reportPermission: business:read · Required: none

Read payments grouped by payment date. Uses the same calculation service as the app, within the connected company and team access.

get_profit_and_loss_reportPermission: business:read · Required: none

Read income, expenses and profit. Uses the same calculation service as the app, within the connected company and team access.

get_sales_by_customer_reportPermission: business:read · Required: none

Read sales and balances grouped by customer. Uses the same calculation service as the app, within the connected company and team access.

get_sales_by_date_reportPermission: business:read · Required: none

Read sales grouped by date. Uses the same calculation service as the app, within the connected company and team access.

get_sales_by_item_reportPermission: business:read · Required: none

Read invoice sales grouped by item. Uses the same calculation service as the app, within the connected company and team access.

get_sales_journalPermission: business:read · Required: none

Read the sales journal and tax calculations. Uses the same calculation service as the app, within the connected company and team access.

get_send_statusPermission: business:read · Required: send_id

Read the status of a queued document email and its provider delivery events. A delivery_unknown result requires checking the provider before deciding whether to send again.

get_subscription_linkPermission: business:read · Required: none

Open official pricing and access information. Subscription purchases, when available, require browser confirmation.

get_tax_reportPermission: business:read · Required: none

Read invoice tax totals and taxable sales. Uses the same calculation service as the app, within the connected company and team access.

list_customer_remindersPermission: business:read · Required: customer_id

Read reminders for a saved customer.

list_customer_tagsPermission: business:read · Required: none

List the company's saved customer tags.

list_expense_categoriesPermission: business:read · Required: none

Read the account owner's expense categories, which are shared across their companies.

list_expensesPermission: business:read · Required: none

Read expenses in the connected company.

list_notificationsPermission: business:read · Required: none

Read notifications addressed to the signed-in user for the connected company.

list_payment_recordsPermission: business:read · Required: document_id

Read payment records for an invoice. These records describe payments; this tool does not move money.

list_pdf_templatesPermission: business:read · Required: none

List the existing PDF designs available to this account.

list_taxesPermission: business:read · Required: none

Read saved company taxes and rates.

mark_notification_readPermission: settings:write · Required: notification_id, request_id

Mark a notification as read.

pay_invoices_in_fullPermission: payments:write · Required: document_ids, request_id

Record payments for the outstanding balances of selected invoices. This does not charge customers or move money.

prepare_customers_importPermission: customers:write · Required: csv, request_id

Upload CSV text for a saved customers import. Returns a batch ID, column mapping and preview; does not create catalog entries.

prepare_items_importPermission: items:write · Required: csv, request_id

Upload CSV text for a saved items import. Returns a batch ID, column mapping and preview; does not create catalog entries.

preview_customers_importPermission: customers:write · Required: batch_id, columns

Preview a prepared import using the specified column mapping.

preview_items_importPermission: items:write · Required: batch_id, columns

Preview a prepared import using the specified column mapping.

preview_send_documentPermission: documents:send · Required: document_id, to, subject, message

Prepare a review of this operation without performing it. Email a document PDF to the explicitly specified recipients. Show the preview and obtain confirmation first. Returns a send_id; use get_send_status to check delivery. Retry the same request_id after a connection failure.

record_deposit_paymentPermission: payments:write · Required: document_id, amount, date, request_id

Record a received invoice deposit and update both deposit paid and the invoice balance. Does not transfer money.

record_paymentPermission: payments:write · Required: document_id, amount, date, request_id

Record a payment received for an invoice and update its paid amount and balance. Does not charge a card or move money.

search_customersPermission: business:read · Required: none

Find saved customers in the connected company.

search_documentsPermission: business:read · Required: document_type

Find invoices, estimates or purchase orders in the connected company. Results are paginated and respect the team member's data access.

search_itemsPermission: business:read · Required: none

Search the saved item catalog and current stock quantities.

send_documentPermission: documents:send · Required: confirmation_token, request_id

After the user confirms the exact preview in the conversation, execute that preview. Email a document PDF to the explicitly specified recipients. Show the preview and obtain confirmation first. Returns a send_id; use get_send_status to check delivery. Retry the same request_id after a connection failure.

set_customer_tagPermission: customers:write · Required: customer_id, request_id

Assign one customer tag, or remove the assignment by omitting tag_id.

set_document_statusPermission: documents:write · Required: document_id, status, request_id

Change an estimate or purchase order's business status, applying the existing inventory rules. Invoice payment status is determined by its payment records.

set_invoice_depositPermission: documents:write · Required: document_id, deposit_type, deposit_value, request_id

Configure the deposit requested on an invoice. This does not record a payment or charge the customer.

update_company_settingsPermission: settings:write · Required: request_id

Update only supplied company settings. Currency changes affect how existing documents are displayed; do not change currency just to create one invoice in another currency. Number counters are the next numbers to allocate.

update_customerPermission: customers:write · Required: customer_id, request_id

Edit a saved customer. Omitted fields remain unchanged; existing invoice customer snapshots remain unchanged.

update_customer_reminderPermission: customers:write · Required: reminder_id, message, remind_at, request_id

Edit a pending customer reminder.

update_customer_tagPermission: customers:write · Required: tag_id, name, color, request_id

Rename a customer tag or change its color.

update_documentPermission: documents:write · Required: document_id, request_id

Edit a document. Omitted fields retain their existing values. When supplying items, include every retained line and its line_id; omitted lines are removed. Catalog records and payment records are not edited by this tool.

update_expensePermission: expenses:write · Required: expense_id, request_id

Edit an expense; omitted fields remain unchanged and the total is recalculated.

update_expense_categoryPermission: expenses:write · Required: category_id, name, request_id

Rename an account-wide expense category.

update_invoice_reminder_settingsPermission: settings:write · Required: due_enabled, due_days, due_time, overdue_enabled, overdue_days, overdue_time, request_id

Set account-wide due and overdue invoice reminders. Owner only; settings apply across their companies.

update_itemPermission: items:write · Required: item_id, request_id

Update a saved catalog item. This does not change historical document line snapshots. Stock changes create inventory movement records.

update_taxPermission: settings:write · Required: tax_id, request_id

Edit a saved company tax. Existing document tax snapshots are unchanged.

4. Ask for help

“Pocket Invoice help: what features can I use with this connection?”

The assistant calls get_help and returns the currently enabled tools within your granted permissions, along with this manual and a working example. Team permissions are checked when each business action is called.

codex mcp --help manages MCP connections. Pocket Invoice’s get_help explains invoice and business features.

5. Choose your permissions

Permission	What it allows
Read account data	Read records and generate PDFs for the connected company.
Create and edit documents	Invoices, estimates, purchase orders and document customer/item details.
Send documents	Off by default. Requires reviewing and confirming each send in the chat.
Manage customers	Create and edit the saved customer catalog.
Manage items and stock	Create and edit catalog items and inventory.
Manage payment records	Record received payments and deposits.
Manage expenses	Create and edit expenses and categories.
Manage company and settings	Company settings, file uploads and account preferences.

All displayed permissions except sending are checked initially. You can change them before approval. A connection belongs to one company. Adding permissions or changing the company requires a new authorization. Revoke a connection in AI connections.

Inline customers and items are saved as document details. They do not automatically become records in your customer or item catalog. Created records retain the entry point and available AI client identity; a client-reported name is not a verified identity.

6. Optional workflow skill

MCP connects the assistant to your account and runs the actions. The optional skill explains the invoice, PDF and sending steps. You can use MCP without installing the skill.

With Node.js installed, run this command to install the skill for Codex:

npx skills add https://www.freedominvoice.com/mcp/downloads/pocket-invoice-workflow.zip --agent codex --global

The command runs Vercel’s skills installer from npm and downloads the Pocket Invoice skill. It does not install a local server or authorize your account.

Download Codex skill ↓

To install manually, extract the ZIP and put the pocket-invoice-workflow folder in ~/.agents/skills/. In Codex, invoke $pocket-invoice-workflow or describe an invoice task. Connect and authorize MCP separately using step 1.

No separate Pocket Invoice npm package is needed. The public plugin-directory listing is not yet available. Installer instructions → · Official Codex skill locations →

7. When something goes wrong

The connection is missing: Check that the server is enabled and uses the URL above. Authenticate, then open a chat with the connection available. CLI users can check codex mcp list and /mcp.
The session or authorization expired: Authenticate again. If access was revoked or a refresh token was rejected, reconnect the account instead of reusing the failed token.
A permission is missing: Authorize again with the required permission and the correct company. The connection cannot exceed your team permissions.
The invoice exists but the PDF failed: Ask for a PDF of the saved invoice ID. Do not create the invoice again.
The download link expired: Ask for a new PDF link for the existing document.
The Web Preview will not open: Sign in to the account that owns the document. Access to another account’s or company’s documents is restricted.
An email has an uncertain status: Ask for the sending status before trying again. Accepted by the mail provider does not prove inbox delivery.

Create invoicesfrom your AI chat.