MCP
Let compatible assistants use Invoicey through validated tools.
Invoicey exposes its invoicing tools over the Model Context Protocol, so an assistant that speaks MCP can look up companies, build invoices, issue them, mark them paid and email them.
MCP tools call the same handlers and validate against the same schema as the web app. The supported fields and rules stay aligned.
Connect
Streamable HTTP at https://invoicey.app/api/mcp. OAuth-capable clients can discover the authorization server from the endpoint, sign in and approve a specific workspace. See ChatGPT setup for interactive invoice views.
For personal-key clients, create a key under Workspace → API keys — see API keys.
{
"mcpServers": {
"invoicey": {
"url": "https://invoicey.app/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Your key resolves to your user and binds every tool call to your default workspace (updated when you switch workspaces or change it under Workspace → API keys).
Client-specific setup: Cursor · Claude Code.
The tools
| Tool | Purpose |
|---|---|
lookup_business | ARES lookup by IČO |
search_business | ARES search by company name |
get_workspace | Connected workspace and default issuer |
list_clients | Saved client summaries |
update_invoice_draft | Correct a saved draft |
issue_invoice | Issue a reviewed draft |
create_invoice | Build, validate and render an invoice |
list_invoices | Summaries, with status and displayStatus |
get_invoice | One invoice with its full payload |
mark_invoice_paid | Record payment |
send_invoice_email | Email the PDF and ISDOC |
list_presets · get_preset · save_preset · delete_preset | Manage presets |
Full input and output shapes: MCP tool reference.
Presets
The workspace business registry controls the seller. create_invoice reads the default issuer
server-side and does not accept issuer or preset IDs. Complete your business details in Invoicey before
drafting. If no default is marked, the tools use the first saved business; setting the default
explicitly avoids ambiguity. A connected workspace without a usable issuer cannot create a draft.
The preset tools can store and inspect issuer snapshots or invoice template data. These
are reusable data, not a way to override the invoice tool's seller. An assistant reusing template
facts must still include them in the confirmed draft; create_invoice does not take a template
preset ID or automatically merge a preset.
Validation is not verification
The schema guarantees an invoice is well-formed, not that it is right. It cannot tell that the model billed 40 hours when you worked 4. Read what it produced — issuing and sending are the irreversible steps.
Try a complete request
Look up NFCtron by IČO. Using my workspace default issuer, invoice them 40 hours of consulting at 1 800 CZK, due in 14 days. Return the draft for review; do not issue it yet.
Limitations
- One workspace per key. A personal key binds to your default workspace; there is no per-call override. Change the default via the sidebar switcher or Workspace → API keys.
- OAuth scopes and roles. OAuth grants distinguish read and write access. Both OAuth and personal keys enforce current membership, role and plan permissions.
- No import tool. Historical import is web-only by design.
- No
unmark_invoice_paid. Web only. - Issuer setup stays in the web app. MCP reads the configured workspace issuer.
- Client persistence follows drafts. There is no standalone client-create tool, but saving a draft can create or reuse its confirmed client in the workspace registry. Managed client catalogs remain restricted.
- Recurring schedules stay in the web app. MCP does not configure unattended issuance or historical import.