Skip to content
kove

MCP (runtime agents)

The MCP is a secondary surface. The main way to use kove is the hosted API, which your coding agent wires into your app. The MCP is for a different case: a runtime agent that needs to build or edit documents on the fly, for example an assistant inside your product that makes a PDF live during a conversation.

The MCP (Model Context Protocol) lets an agent like Claude Code do the work end to end: build the JSON document, validate it, and render it, and even sign in or upgrade the plan when needed. The browser opens on its own.

Because the document format is built into the MCP tools, the agent already knows how to write a valid document. It does not have to guess the format, so it gets it right the first time.

Add it to Claude Code

Section titled “Add it to Claude Code”
Terminal window
claude mcp add kove -- npx @kove/mcp

That connects the server over stdio. From there, in the chat:

“Create an invoice for Globex with 3 service line items, 21% tax, and page numbers, and render it with kove.”

The agent builds the JSON, calls validate_document, and then render_document to get the PDF.

Two modes

Section titled “Two modes”

The same MCP works locally or against the cloud, depending on whether KOVE_API_KEY is in the environment:

  • Local (no KOVE_API_KEY): validates and renders on your machine with Chromium, no account. Zero friction to start.
  • Cloud (with KOVE_API_KEY): uses the hosted service and enables the account tools (login, upgrade, status).

Local tools

Section titled “Local tools”

Always available, no account.

validate_document

Section titled “validate_document”

Validates a document. Returns whether it is valid and, if not, the list of errors with their path.

validate_document({ document: { body: [ { type: "heading", text: "Hello" } ] } })
→ ✓ valid document (spec https://spec.kove.dev/document/v0.json)

render_document

Section titled “render_document”

Validates and renders a document to PDF. Returns the path of the generated PDF. Takes outputPath (default kove-output.pdf).

render_document({ document: { … }, outputPath: "invoice.pdf" })
→ ✓ rendered to invoice.pdf (28431 bytes)

Cloud tools

Section titled “Cloud tools”

For account and billing. They open the browser for the user when needed.

login

Section titled “login”

Signs in to kove cloud with device-flow: opens the browser, waits for the user to authorize, and saves the API key. No arguments. Since the agent cannot type in the terminal, the tool returns the URL and the verification code so the agent can show them to you if the browser did not open on its own.

upgrade

Section titled “upgrade”

Creates a Stripe checkout to upgrade the plan and opens the browser to pay. Takes plan (default pro). Requires a session. The plan activates automatically after payment (webhook). The tool does not wait, it just gives you the URL.

account_status

Section titled “account_status”

Returns the account status: plan, period usage, limit, and remaining. Requires a session.

account_status()
→ Plan: free
  Period usage: 12/100
  Remaining: 88

The full agent-native flow

Section titled “The full agent-native flow”

An agent can take you from “I need an invoice” to “PDF in the cloud and plan up to date” without you touching the terminal:

  1. Build the JSON document (it already knows the format).
  2. validate_document → fix if needed.
  3. render_document → PDF.
  4. No session and want the cloud? login opens the browser; you sign in; the key comes back on its own.
  5. Out of quota? account_status detects it and upgrade opens the checkout.