Private beta

MCP setup reference

Connect an AI client to Paflio.

Copy the server URL, sign in, then choose one Workspace and a permission preset. Paflio exposes complete record details plus scoped tools for edits, workflows, exports, and direct document intake.

View setup

Available · Sign-in required

Production server URL

This is the canonical production URL. Connecting opens Paflio sign-in and consent; access requires an active eligible trial, Solo subscription, or paid Business seat.

Server URL

https://mcp.paflio.com/mcp

Quick setup

Paste the exact configuration.

These examples use Paflio’s canonical remote endpoint. Keep the complete /mcp path.

Copy both commands

Codex CLI

Add the remote server, then start Paflio’s OAuth sign-in flow.

Codex CLI configuration

codex mcp add paflio --url https://mcp.paflio.com/mcp
codex mcp login paflio

Copy into config.toml

Codex config.toml

Use this in ~/.codex/config.toml or a trusted project’s .codex/config.toml.

Codex config.toml configuration

[mcp_servers.paflio]
url = "https://mcp.paflio.com/mcp"
auth = "oauth"
default_tools_approval_mode = "prompt"

Supported configuration path

ChatGPT desktop app

Open Settings, then MCP servers.
Select Add server and choose Streamable HTTP.
Enter https://mcp.paflio.com/mcp, save, then restart.
Select Authenticate and complete Paflio sign-in and consent.

Compatibility required

Other MCP clients

Choose Streamable HTTP as the transport.
Use https://mcp.paflio.com/mcp as the complete server URL.
Use OAuth discovery; do not paste Clerk credentials or a Paflio session token into the client.
The client must support MCP 2026-07-28 and OAuth Client ID Metadata Documents (CIMD).

Connection contract

Everything a client needs to identify the server.

The connection uses the current MCP protocol, a stateless HTTP transport, and OAuth discovery. Paflio credentials stay in the browser sign-in flow.

Endpoint: https://mcp.paflio.com/mcp
Protocol: MCP 2026-07-28
Transport: Stateless Streamable HTTP · POST
Authentication: OAuth authorization code + PKCE S256
Access presets: View only · Edit records · All capabilities
Scoped capabilities: read · export · upload · edit · review · approve · send · destructive
Grant boundary: One authenticated user · one client · one Workspace

Discovery URLs

For clients and implementers

A compatible client discovers these automatically. They are listed here for validation and troubleshooting.

Protected resource metadata

https://mcp.paflio.com/.well-known/oauth-protected-resource/mcp

Authorization server metadata

https://mcp.paflio.com/.well-known/oauth-authorization-server

Authorization endpoint

https://mcp.paflio.com/authorize

Token endpoint

https://mcp.paflio.com/oauth/token

Public keys

https://mcp.paflio.com/.well-known/jwks.json

Tool reference

Eighteen scoped bookkeeping tools.

All tool results are limited to the Workspace approved during OAuth. No tool accepts a user ID, Organization ID, or Workspace ID from the model.

get_paflio_context

Confirm the active context

Returns the Workspace bound to the connection, your role, subscription source, granted scopes, and current capabilities.

No arguments: Call this first to confirm the Workspace and available access.

list_bookkeeping_records

List bookkeeping records

Returns one bounded page of record summaries from the connection-bound Workspace.

kind: Required: ledger, inbox, invoice, quote, or claim.
financialLane: Required for ledger and inbox: expense or income. Omit it for invoice, quote, and claim.
cursor: Optional pagination cursor from the previous response; maximum 1,024 characters.
limit: Optional integer from 1 to 50. Default: 20.

get_bookkeeping_record

Get one record

Returns every populated user-facing field for one authorized record. Database, storage, operation, and authorization IDs are excluded.

kind: Required: ledger, inbox, invoice, quote, or claim.
reference: Required opaque reference returned by list_bookkeeping_records; it is bound to this client, grant, Workspace, and record kind.
financialLane: Required for ledger and inbox: expense or income. Omit it for invoice, quote, and claim.

search_bookkeeping_records

Search bookkeeping records

Searches user-facing text across recent Ledger, Inbox, Invoice, Quote, and Claim records and says when the bounded scan is incomplete or more matches exist.

query: Required search text, from 1 to 256 characters.
kinds and financialLanes: Choose the record kinds and Expense or Income lanes to search.
limit: Optional result limit from 1 to 50. Default: 20.

list_bookkeeping_resources

List reusable resources

Returns bounded pages of Customers, Workspace bookkeeping settings, or eligible members with opaque references for relationship-safe edits.

kind: Required: customer, setting, or member.
settingKind: Required only for settings: category, department, payment_account, document_kind, or document_type.
financialLane: Required only for document_kind settings: expense or income.
cursor and limit: Use the prior cursor and a page limit from 1 to 50.

get_bookkeeping_resource

Get one reusable resource

Returns every populated user-facing field for one Customer, Workspace bookkeeping setting, or eligible member without exposing its database row ID.

kind: Required: customer, setting, or member.
reference: Required opaque reference returned by list_bookkeeping_resources.

begin_bookkeeping_batch

Start a direct upload batch

Available with All capabilities. Creates a durable Income or Expense batch and returns one short-lived, single-use upload capability for each accepted file. A compatible local host streams the approved file bytes directly; no browser upload opens.

financialLane: Required: income or expense. The authenticated connection supplies the Workspace.
operationId: Required stable retry identity. Reusing it with changed inputs is rejected.
files: A bounded manifest containing client file ID, filename, supported MIME type, byte length, SHA-256, and page-count hint. File bytes do not belong in this MCP request.

finalize_bookkeeping_batch

Verify and finalize a batch

Rechecks the connection, current server policy, uploaded length, magic-byte type, SHA-256, and server-derived PDF page count before advancing valid files into the existing Income or Expense Inbox workflow.

batchId: Required durable batch ID returned by begin_bookkeeping_batch. Finalization is safe to retry and never infers paid or outstanding status.

get_bookkeeping_batch

Check or resume a batch

Returns durable per-file states plus resulting Inbox and Review references. Retry the original operation and manifest to receive capabilities only for files that have not started or can be retried.

batchId: Required durable batch ID. It remains bound to the authenticated user, client, grant, Workspace, and financial lane.

update_bookkeeping_record

Save reversible edits

Available with Edit records or All capabilities. Saves editable fields on an Expense Ledger record, Inbox Review draft, or Invoice, Quote, or Claim draft through the same validation and permission rules as Paflio Web.

kind and reference: Required record kind and opaque reference from the current connection.
concurrency token: Use expectedRevision, expectedUpdatedAt, or expectedDraftUpdatedAt from the latest detail read, as required by the selected kind.
operationId: Required stable retry key, 8–160 letters, numbers, colons, underscores, or hyphens.
fields: A bounded, kind-specific complete edit payload. Stale, invalid, unauthorized, or ineligible-lifecycle edits do not mutate the record.

manage_bookkeeping_resource

Create or update a resource

Available with Edit records or All capabilities. Creates or updates Customers and creates Workspace bookkeeping settings. Archival remains a separate confirmed destructive action.

action: Required: create_customer, update_customer, or create_setting.
reference and revision: Customer updates require the current opaque Customer reference and revision.
resource fields: Provide the bounded Customer or setting fields required by the selected action.

create_bookkeeping_draft

Create a document draft

Available with Edit records or All capabilities. Creates an Invoice, Quote, or Claim draft through current Web defaults and workflow prerequisites.

kind: Required: invoice, quote, or claim.
operationId: Required stable retry key for idempotent creation.
draft identity: Invoices and Quotes require a clientDraftId; Claims require a name and optional description.

prepare_bookkeeping_action

Prepare an exact high-risk action

Validates and previews one Review, lifecycle, delivery, export, or destructive action, then returns a short-lived Paflio confirmation URL. Preparing never changes a record.

command: The exact target, action, concurrency token, operation ID, and material details. A later tool call must use the matching one-time confirmation.

perform_bookkeeping_review_action

Assign or complete a Review

Available with All capabilities after exact Paflio confirmation. Reuses current Review permissions, revisions, duplicate checks, and idempotency.

command and confirmationReference: Pass the unchanged assign_review or complete_review command and its approved one-time confirmation.

perform_bookkeeping_lifecycle_action

Advance a document workflow

Available with All capabilities after exact Paflio confirmation. Covers Invoice issue/payment, Quote send/decision/expiry/conversion/revision, and Claim submit/approval/rejection/return outcomes.

command and confirmationReference: Pass an eligible revision-checked lifecycle command and its approved one-time confirmation.

perform_destructive_bookkeeping_action

Perform a destructive action

Deletes, voids, cancels, or archives one eligible Ledger, Invoice, Quote, Claim, Customer, or setting target after a separate short-lived confirmation from a recent Paflio session.

command and confirmationReference: Pass the exact concurrency-checked destructive command and approved one-time confirmation.

send_bookkeeping_document

Send an Invoice or Quote email

Queues an Invoice or Quote email through Paflio’s recipient, suppression, immutable-PDF, secure-link, idempotency, and reconciliation safeguards after the user confirms the exact recipient and options.

command and confirmationReference: Pass send_invoice or email_quote with the current document revision, recipient email, stable operation ID, and matching approval. Invoice delivery also selects PDF-and-link or link-only mode.

export_bookkeeping_records

Export a Ledger CSV page

Returns one confirmed, formula-safe CSV page for an Expense or Income Ledger lane. Continue with another explicitly confirmed page when isDone is false.

command and confirmationReference: Choose one lane, optional date range and cursor, a limit up to 50, and a stable operation ID; then approve that exact page.

Authentication and access

Sign in once. Authorization is checked on every call.

Clerk authenticates your Paflio account in the browser. Paflio then shows the requesting client, permission, and exact Solo or Business Workspace before you allow access.

An authenticated Paflio account with an active eligible 30-day Solo trial
A current Solo subscription
A current paid Business seat with active Workspace membership

One connection, one Workspace

Each grant stays fixed to the Workspace shown during approval. Every call rechecks the account, membership, scope, capability, and billing entitlement.

Troubleshooting

Errors that tell you what to do next.

Error code	Next action
`MCP_UNAUTHENTICATED`	Authenticate the Paflio connection again.
`MCP_ACCESS_DENIED`	Check the connected account, Workspace membership, and grant, then reconnect.
`MCP_BILLING_REQUIRED`	Start an eligible trial or restore the applicable Solo subscription or Business seat.
`MCP_SCOPE_REQUIRED`	Reconnect with the permission required by the tool.
`MCP_REQUEST_INVALID`	Correct the tool arguments. Ledger and Inbox calls require financialLane.
`MCP_RECORD_REFERENCE_INVALID`	List the records again and retry with a reference from the current connection.
`MCP_REVISION_CONFLICT`	Read the record again, reconcile the newer values, and retry with its current concurrency token.
`MCP_OPERATION_REUSED`	Use a new stable operation ID; the supplied ID was already bound to a different confirmed request.
`MCP_ACTION_UNAVAILABLE`	Check your role and the record’s current lifecycle; this edit is not currently available.
`MCP_CONFIRMATION_REQUIRED`	Open the short-lived Paflio confirmation URL, review the exact action, approve it, and retry unchanged.
`MCP_CONFIRMATION_ALREADY_USED`	Prepare and approve a new confirmation for this action.
`MCP_RESULT_TOO_LARGE`	Request a smaller page by reducing limit and continue with the returned cursor.
`MCP_SERVICE_UNAVAILABLE`	Try again later. If the error continues, contact Paflio support.

First prompts

Start by checking context.

Ask the client to confirm the Workspace before requesting a list or individual record.

Use get_paflio_context and tell me which Workspace this connection can access.
List the 20 newest Expense Ledger records in this Workspace.
List my Invoices, get the newest one by its opaque reference, and summarize every populated field.
Read this Invoice draft, update its notes and line items with its current revision, then read it again to verify the saved totals.
Search for Prairie Office, show every populated field on the matching record, and do not make changes.
Prepare an Expense Ledger CSV export for September, open the Paflio confirmation, then export each bounded page.
Start an Income bookkeeping batch for these approved invoice PDFs, upload each file through the returned capability, finalize the batch, and report its Inbox references.

Before you connect

Only approve a client you trust.

Bookkeeping fields returned by a tool become available to that AI client and may be governed by its account and retention settings. Never paste your Paflio password, Clerk token, or MCP access token into a prompt or configuration file.

Read the Paflio Privacy Policy