Connect with MCP

Set up sending companies and manage customers and invoice drafts from Codex, using a default sender automatically.

Billtyme’s MCP interface provides sending-company setup, editing, customer management, and invoice drafts. Each connection is scoped to the WorkOS organization selected during authorization.

A default sender for routine operations

An organization can have multiple sending companies. Billtyme uses its default sender when you create an invoice or manage customers, so you do not need to choose a company every time. To use another sender for one operation, supply sending_company_id. This leaves the default unchanged and can only select a company within the connected organization.

Customers are the recipients you invoice; each belongs to a sending company. To access a different WorkOS organization, reconnect and authorize that organization.

Set up and edit sending companies

Start with list_sending_companies and get_default_sending_company. If no companies exist, create_sending_company sets up the first sender and makes it the default automatically. Provide its legal name, postal address, and default currency. Additional senders do not replace the default.

Use update_sending_company to change an address, legal name, tax identifiers, or billing defaults. Read the company first and pass its current version as input.expected_version. Only supplied fields change; a supplied address replaces the complete address. Use null to clear optional email, trading name, or external reference, and [] to clear identifiers. Existing invoice snapshots keep the details they were created with.

set_default_sending_company changes the default for everyone in the organization, including existing MCP connections. Customers and invoices remain with their original sending company. Older accounts with several senders and no default need this choice once; an older account with one active sender uses it automatically.

Available tools

Tool	Purpose
`list_sending_companies`	Discover sending companies in the organization
`get_sending_company`	Read company details and the current version
`get_default_sending_company`	Read the default sender, or `data: null` if setup is needed
`create_sending_company`	Set up a sending company; the first becomes the default
`update_sending_company`	Edit company identity, address, and billing defaults
`set_default_sending_company`	Change the organization-wide default sender
`list_customers`	Find customers, optionally by external reference
`get_customer`	Read one customer
`create_customer`	Add a customer to the connected sending company
`list_invoices`	Find invoices by customer, status, or external reference
`get_invoice`	Read an invoice and its calculated totals
`create_invoice_draft`	Prepare a draft for an existing customer

The tools visible to you depend on your WorkOS permissions. Company discovery needs company read permission; creation, edits, and default changes need company write permission. Draft creation does not issue or send the invoice.

For writes, supply an idempotency_key and reuse it with the same arguments when retrying the same operation. Use a new key for a new intended operation. Money uses integer currency minor units, and quantities use decimal strings.

If the default sender changed after a write, retry with the original sending_company_id and the same key and input. Billtyme rejects reuse of the key under a different sender rather than creating a duplicate. Replaying a default-change command returns its original result without changing the current default again.

Connect Codex

Your administrator must first configure the deployed /mcp URL and WorkOS OAuth integration. Use that public URL in place of the example below:

codex mcp add billtyme --url https://api.example.com/mcp
codex mcp login billtyme --scopes openid,profile,email,offline_access

Complete WorkOS sign-in and select your organization when prompted. Start with a request such as “Show my sending companies” or “Help me set up my first sending company.”

The retained REST API still uses company IDs in its paths. MCP calls the same billing services and checks every selected sender against the authorized organization.