MCP Server

The InvoicePig MCP server exposes a single tool: generate invoice PDFs from JSON using your API key—no draft or history access via MCP.

Quick start

Pick your MCP client, paste the JSON, restart the client if needed, then try the prompts. For environment variables and HTTP details, see Setup & configuration.

1. Create an API key

In Settings, generate an MCP API key. It starts with pig_live_ —replace <API_KEY> in every snippet below.

Recommended: Streamable HTTP to hosted InvoicePig—no local build. Merge into mcpServers in your client config.

{
  "mcpServers": {
    "invoicepig": {
      "url": "https://invoicepig.com/api/invoicepig-mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

Then try prompts like:

  • Call invoicepig_generate_pdf with items, currency, and layout.
  • Generate a PDF from JSON including logo and theme colors.

What is MCP?

Model Context Protocol is an open standard so AI apps can call tools and use resources in a structured, secure way. InvoicePig's MCP server gives your assistant:

  • ·Stateless PDF — send invoice JSON (same fields as the web editor) and get a base64 PDF; nothing is stored via MCP.
  • ·Account-scoped access — every request uses your API key and resolves subscription tier for layout rules.
  • ·Same rules as the web app — premium-only layouts return 403 for free accounts; PDF watermark/footer behavior matches the in-app PDF export.

How it works

Three steps from key to automated invoicing.

1. Generate a key
Create an MCP API key in Settings. It authenticates every tool call to your account.
2. Configure your agent
Point your MCP client at the built server and set INVOICEPIG_API_KEY (production defaults to invoicepig.com). Use INVOICEPIG_API_URL for local dev or preview deployments.
3. Generate PDFs
Agents call invoicepig_generate_pdf with invoice JSON and return base64 PDF bytes to the user.

Core concepts for integrators

How InvoicePig data maps to tools and HTTP—read this before wiring an agent.

One tool, one endpoint
MCP exposes only invoicepig_generate_pdf → POST /api/mcp/invoices/generate-pdf. Payload matches the web editor JSON (items, labels, layout, colors, logo, payment fields, currency, dates).
Layouts & watermark
Premium-only layouts return 403 for free accounts. PDF footer branding follows the same rules as the in-app PDF export (premium layouts omit the free-tier footer when entitled).

Setup & configuration

Build the server with bun install and bun run build in invoicepig-mcp-server. The app build runs this automatically; for MCP-only work you can still build there. Then merge the JSON into your client config.

Authentication

The InvoicePig API uses Bearer token authentication. Your API key acts as a secure surrogate for your account.

HeaderAuthorization: Bearer pig_live_...
Key Format

Starts with pig_live_ followed by a secure hash.

Security

Never expose your key in client-side code. The MCP server should run in a secure environment.

HTTP Error Codes
401
Unauthorized

Missing, invalid, or revoked API key.

403
Forbidden

Premium layout used on a free account.

404
Not Found

Rare for PDF generation; usually a routing or deployment mismatch.

500
Server Error

Internal database or validation failure.

Environment Variables
VariableHosted (Default)Self-Hosted
INVOICEPIG_API_KEYRequired (from Settings)Required (from your DB)
INVOICEPIG_API_URLhttps://invoicepig.comYour deployment URL
NEXT_PUBLIC_APP_URL(Automatic)Required for absolute PDF links
INVOICE_SHARE_SECRET(Automatic)Required for signed share links
API key required
Every tool call is authenticated with INVOICEPIG_API_KEY (stdio/npx) or Authorization: Bearer <API_KEY> (remote). Generate the key in Settings. Do not commit keys to git or ship them in client-side apps—the MCP server should run where secrets are safe.

Same JSON snippets as the Quick start tabs—expanded notes and links for each transport.

Recommended for production and cloud agents: no local build, no Node path—your client speaks Streamable HTTP to InvoicePig. Paste the JSON into ~/.cursor/mcp.json (merge into mcpServers if you already have servers). Replace <API_KEY> with your full key from Settings (starts with pig_live_). No local dist/index.js. Streamable HTTP at /api/invoicepig-mcp. For a preview deployment, replace the host with your preview URL. If your client only supports stdio, use npx -y mcp-remote <url> (see mcp-handler client docs).

{
  "mcpServers": {
    "invoicepig": {
      "url": "https://invoicepig.com/api/invoicepig-mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

Common workflows

Tool sequences third-party agents typically implement for user intents.

REST API Map
The MCP tool maps to this REST endpoint (authenticated with your API key).
MethodEndpointDescription
POST
/api/mcp/invoices/generate-pdfStateless invoice PDF (base64 in response body)
Generate Invoice PDF
Create a PDF from JSON without saving to the cloud.
  1. invoicepig_generate_pdf — pass invoice fields (items with stable ids, selectedLayout, primaryColor, logoDataUrl, currency, etc.).
  2. Receive pdf_base64 in the response; decode or save as a file for the user.

Example prompts

Once the server is connected, natural language maps to invoicepig_generate_pdf and POST /api/mcp/invoices/generate-pdf.

PDF generation
  • Generate an invoice PDF from this JSON: company name, three line items, bill-to, currency EUR, layout classic.
  • Create a PDF with primaryColor #1e3a5f, accent, and minimal layout; include logo as a data URL.
  • Return the PDF as base64 for this invoice state without saving anything to my account.

Tool reference

One tool. Read / Write badges indicate typical side effects; PDF generation is read-only with respect to your stored data.

Invoice PDF

Stateless generation: POST JSON that matches the web editor field set; receive base64 PDF. Nothing is stored in the cloud via MCP.

Premium on MCP
Subscription is resolved per API key (same Clerk user as the web app). A premium-only selectedLayout in invoicepig_generate_pdf returns 403 Forbidden for free accounts—surface that and link to pricing. PDF output uses the same rendering pipeline as the web app export (including watermark rules for free-tier layouts).
Compare plans

Troubleshooting

Symptom-first fixes for the most common MCP and API issues.

Tools not listed or "No tools"

Confirm the MCP server is enabled in your client and the JSON is valid. Restart the client after editing config. For stdio, verify invoicepig-mcp-server builds locally and the path to dist/index.js is absolute.

In Cursor, check View → Output and select the MCP log channel for errors.

401 Unauthorized
Key missing, rotated, or wrong header. Regenerate in Settings, update INVOICEPIG_API_KEY or Authorization: Bearer …, and restart the MCP process.
403 when generating (premium layout)
Your JSON uses a layout that requires Premium. Use a free-tier layout (e.g. classic, corporate, formal, minimal) in selectedLayout and retry—or upgrade on the pricing page.
500 or PDF render error
Check that logoDataUrl is a valid data URL if set, and that numeric fields (tax, quantities) are finite. For self-hosted apps, confirm the deployment has the same pdfmake dependencies as production.

FAQ

Common questions about keys, hosting, and behavior.

Learn more

Protocol docs, client guides, and the InvoicePig source.