MCP server

The server needs a client that sends your API key in a request header. Where each one stands today:

If your client doesn't offer you the PDF from a result, check the document with the preview image, and make the final with the API instead: a final made here uses its credit even if your client drops the file.

• You need an API key from Settings. While you try it, give the assistant a Preview only key: it can check and preview, and can never use a credit. A Full access key can also make final documents.
• You need a client where you can set a request header, such as Claude Code or Cursor. Every message carries the key in Authorization: Bearer kt_live_….

The server is at https://kouteisystems.com/api/mcp. It speaks Streamable HTTP and keeps no session: each message stands on its own.

{
  "mcpServers": {
    "koutei-pdf": {
      "type": "http",
      "url": "https://kouteisystems.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${KOUTEI_API_KEY}"
      }
    }
  }
}

claude mcp add --transport http koutei-pdf https://kouteisystems.com/api/mcp \
  --header 'Authorization: Bearer ${KOUTEI_API_KEY}'

{
  "mcpServers": {
    "koutei-pdf": {
      "url": "https://kouteisystems.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:KOUTEI_API_KEY}"
      }
    }
  }
}

The server offers 3 tools. Ask the assistant to start with the first.

The fields of each template are the API's: get_template returns them, and the API reference lists them.

generate_document needs mode. Nothing is assumed: a request never uses a credit unless it says final.

A final's credit is taken only after the PDF has been made. The template tools, a check and a preview cost nothing, and so does every error.

• A preview or a final returns a receipt with document, filename, credit_used, credits_remaining, idempotent_replay and totals, as JSON in the result and as its first text block.
• A preview adds page 1 as an image (image/png, at most 1,000,000 bytes). With include_pdf set to true it also returns the watermarked PDF.
• A final adds the PDF as an embedded resource (application/pdf, base64, at most 2,000,000 bytes before base64). Its uri, such as koutei://documents/doc_….pdf, is a label: the server offers no resources to fetch, and Koutei keeps no copy, so save the PDF from the result.
• Every result's _meta carries com.kouteisystems/status (the HTTP status the API would have answered with) and com.kouteisystems/request-id.

An identical final repeated within 24 hours returns the same document and is not charged again, even if the assistant sends no idempotency_key: the server makes one from your API key and the request. Send your own idempotency_key to choose it; it works like the API's Idempotency-Key, and the same key with a different request is refused with 422 idempotency_key_reused.

• A refused call is a tool result with isError: true. Its JSON is the API's error envelope, the same code, details and credit_used. Errors explains each code. When the API would have said wait, com.kouteisystems/retry-after-seconds gives the seconds.
• The API's limits apply. Each tool call counts toward the key's 120 requests a minute; previews share the account's preview limits with the API and the web app. The API reference lists them.
• Repeating an identical final is free, but limited: a key may replay 60 final documents a minute. Over that, the call is refused with 429 rate_limited and the detail replay_limit; nothing is charged, and the same call replays once the wait is over.
• With no credits left, a final is refused with 402 insufficient_credits.

These are the server's instructions to the assistant, word for word:

• Koutei PDF makes invoice, quote and receipt PDFs from facts you send. Start with list_templates, read get_template for the fields, then generate_document.
• Human review: when a person is in the conversation, make a "preview", show it and get their approval before "final". A preview is watermarked and is never a valid document: never present one as final.
• No invented facts: the seller, the client, tax numbers, bank details, amounts, dates and document numbers must come from the person or their data. If a required value is unknown, ask.
• No sending: this server has no email or delivery tools and never contacts anyone. Delivering the document is the person's own action.
• No legal or tax claims: a document is not asserted to be tax-compliant, an e-invoice or legally valid.
• Credits: only "final" uses a credit (1). "validate", "preview", a repeat of an identical final in the following 24 hours, and every error cost nothing; each result states credit_used.
• Totals: every validate, preview and final result states totals, the figures the document prints (subtotal, discount, tax, total, amount paid, balance due). Quote them from there; do not recompute them.
• Errors: read error.details, fix the named fields and call "validate" again.

The same rules are in the description of generate_document, for clients that don't show instructions.