Skip to content

Konto MCP — Tool & API reference

The 39 tools the connector exposes, grouped by area, with parameters, scopes, return shape, examples, and the write-side rules Konto enforces. This complements the connect guide (connect.md) — that's how to plug it in; this is what each tool does.

Every tool maps to one action on Konto's agent API (/api/v1/agent/*). The assistant sees a tool's description and JSON schema at call time; this document is the human reference plus the cross-cutting contracts that individual schemas can't repeat.

Conventions

  • GUIDs — opaque ids returned by list_* / get_*. You pass them to get_* / update_* / delete_*. GUIDs are not searchable text.
  • Dates — YYYY-MM-DD.
  • Money — ISK numeric unless a currency is set on the record.
  • Scopes — enforced server-side on every call; the connector also hides tools a session's granted scopes don't cover. See the scope column below.
  • Writes are real. Creating an invoice issues and delivers it; marking paid, deleting a cost, revoking an agent all take effect immediately.

Scopes at a glance

Scope Tools it unlocks
manage_customers all konto_*_customer(s)
nav all konto_*_item(s); list/get/update_invoice
create_invoice konto_create_invoice
recurring konto_create_recurring_invoice
cost all konto_*_cost(s) incl. reopen
task all konto_*_task*
sell_product all konto_*_product_sale*
dashboard_data konto_status
(none) konto_list_agents, konto_revoke_agent

Shared value sets — the write contract

These are the fixed code sets and validation rules the write tools share. Getting one wrong is the most common cause of a rejected write.

Tax codes (tax)

Letter code on input → VAT rate. Used by items, invoice line items, and task items.

Code Rate
S 24% standard
AA 11% reduced — note: 11%, not 24%
Z 0% zero-rated

Output may also show E (tax-exempt customer) — that's output-only, driven by the customer's exemption flag, not something you send.

Units of measure (uom)

Free text is rejected — use a code.

Code Unit Code Unit
C62 pieces KWH kWh
KGS kg DAY days
MTR m HUR hours
LTR litres MIN minutes
MTK m² KTM km
MTQ m³ TNE tonnes

Cost codes (type on costs)

Pass a numeric code. The name Items is accepted as an alias for 2353; no other name is. There is no code-lookup tool — if unsure, ask the user or use konto_create_cost (the receipt AI fills the code).

3028 2173 3033 3085 3090 2093 2243 2193 2423 2443 2353 2383 2403
2263 3163 2333 3140 2283 2533 2633 3653 5028 2153 3080 9535

Payment method (how_paid, costs)

1 = Account · 2 = Debit/bank · 3 = Credit card · 4 = Owner cash.

Invoice delivery (delivery, customers → server output_select)

2 = e-invoice/XML (requires trading_partner_id) · 3 = email (default) · 4 = PDF. Delivery 3/2 means Konto emails/sends the invoice to the customer when one is issued. The API ignores delivery on create (it makes an email customer, or an e-invoice customer when trading_partner_id is sent) and an email is required either way, so konto_create_customer sets any other delivery with a follow-up update; konto_update_customer honours it directly.

Accounting status (accounting_status)

  • Invoices (update_invoice): Created, Posted, Skipped, Error.
  • Costs (update_cost): Posted, Skipped, Error — and only on a cost that is currently Created. Created and New are not settable here — reach New via konto_reopen_cost. Posted is terminal (exported to accounting, locked; can't be edited or deleted). The optional accounting_message is not stored by the production API yet (accepted and dropped); a newer Konto release keeps it.

kennitala

10 digits, no dash, mod-11 checksum (validated on customer create/update).

Invoice amount rule

amount is required and validated against the line items. The server recomputes Σ(unit_price × qty − discount) + VAT and rejects the call on any mismatch. Send amount = the line-item total including VAT, rounded to 2 dp.

Invoice dates

The server requires settlement_date (final due date / eindagi) and enforces issue_date ≤ due_date ≤ settlement_date. The tool auto-fills the chain when you omit dates (issue → today, due → issue, settlement → due), so a bare "invoice this customer" works; override any of them explicitly when needed.

Inline invoice lines

A new line (add_new: 1) also requires an item_number; the tool auto-generates a unique one when you don't supply it. Existing-item lines (by guid) need none.

Account

Tool Scope Purpose
konto_status dashboard_data Health check + identity: company name, kennitala, username, and the environment (dev vs prod/live). Call it first to confirm which account and environment you're on.
konto_list_agents — List agent clients authorized on the account, with granted scopes.
konto_revoke_agent — Revoke an agent by agent_id. Immediately kills that agent's tokens. Don't revoke the id this connector is using — it cuts your own access.

Customers — manage_customers

Tool Purpose
konto_list_customers List, paginated. search matches the name only; find by kennitala with kennitala (a substring match — pass all 10 digits). Email is not searchable.
konto_count_customers Count, optional search (name only).
konto_get_customer One customer in full by guid.
konto_create_customer Create. Returns the new customer's GUID in result (not the record — konto_get_customer fetches it).
konto_update_customer Update; send only the fields to change (fetch first to preserve others). Returns the GUID.

konto_create_customer — required: name, kennitala, email. Optional: delivery (2/3/4, default 3=email), trading_partner_id (required if delivery=2), address, zip, city, phone (stored as the API's phone_number), lang (is/en, default is), currency (default ISK), country (default IS). email is always required on create, also for delivery=4.

The API ignores the delivery method on create: the customer is always created with email delivery, or e-invoice delivery when trading_partner_id is sent. So when delivery asks for something else (typically 4, PDF), the tool follows the create with a update (output_select). If that update fails the response carries a warning with the GUID — the customer then keeps the API's delivery, so fix it before invoicing. delivery=2 without trading_partner_id is refused up front, because the API would otherwise create an email customer.

{ "name": "Acme ehf", "kennitala": "1203894569", "email": "acme@example.is", "delivery": "3" }

The field is kennitala, not registration_no — the server rejects the latter.

Items (products & services) — nav

Tool Purpose
konto_list_items / konto_count_items / konto_get_item List / count / get by guid.
konto_create_item Create a product or service. Returns its GUID.
konto_update_item Update; send only the fields to change (active: "0" deactivates). Returns the GUID.

konto_create_item — required: description, unit_price (numeric string, dot-decimal, e.g. "1990.00"). Optional: uom, tax, category, active (default "1"). The Konto API requires uom and tax and has no defaults; the tool fills them in when omitted — uom C62 (pieces) and ⚠️ tax Z = 0% — so set S or AA for taxable items.

{ "description": "Ráðgjöf", "unit_price": "18500.00", "uom": "HUR", "tax": "S" }

konto_update_item — the API resets the price to 0 when an update leaves out unit_price, so when you omit it the tool reads the item first and sends its current price (the response then carries a note saying so). That read reports prices rounded to whole numbers: an item stored with decimals — often a net price worked back from a VAT-inclusive one, e.g. 415.32 for 515 incl. 24% VAT — comes out rounded. Pass the exact unit_price when you know it.

Invoices — nav (read), create_invoice, recurring

Tool Scope Purpose
konto_list_invoices nav List, filter by accounting_status + date range.
konto_get_invoice nav One invoice in full by guid.
konto_create_invoice create_invoice Create + issue an invoice.
konto_create_recurring_invoice recurring Create a recurring schedule.
konto_update_invoice nav Change only the accounting status (+ message). Cannot edit amounts, dates, lines, or customer.

konto_create_invoice — required: customer_guid, amount, items. Key optional: currency (ISK), issue_date / due_date / settlement_date (auto-filled chain), type (invoice; the tool also offers quote, but the API refuses quotes for now), is_claim (1 = a bank claim/krafa — consumes claim quota), mark_paid (1 only if already paid), discount fields.

Line items — existing catalogue item by guid, or inline with add_new: 1 + description + unit_price + tax + uom (qty always required):

{
  "customer_guid": "…",
  "amount": 74400,
  "items": [
    { "add_new": 1, "description": "Consulting", "qty": 3,
      "unit_price": 20000, "tax": "S", "uom": "HUR" }
  ]
}
amount here = 3 × 20,000 = 60,000 net + 24% VAT (14,400) = 74,400. A wrong total is rejected. See the amount rule above.

This issues and delivers a real invoice. On a customer with email/e-invoice delivery, Konto sends it to that customer. Confirm before invoicing.

Costs (expenses) — cost

Tool Purpose
konto_list_costs List with filters (accounting_status, type, supplier_id, date range). Newest issue date first; sort = date_desc (default) / date_asc / created_desc / created_asc. Heavy file/xml fields stripped.
konto_count_costs Count, same filters.
konto_get_cost One cost in full by guid (incl. file/xml).
konto_create_cost Create from a receipt file (jpg/jpeg/png/gif/pdf, ≤5 MB) — Konto's AI extracts amount/supplier/VAT/code. Async: re-fetch to read extracted fields.
konto_create_cost_adv Create from structured fields you already have.
konto_update_cost Change only the accounting status: Posted / Skipped / Error, and only while the cost is Created. accounting_message is not stored by production yet.
konto_reopen_cost Move an approved (Created) cost back to New so it can be edited; re-approving regenerates its bookkeeping XML. Not on Posted.
konto_delete_cost Soft delete: restorable in Konto (Deleted view of the cost list) for 28 days, then removed; no API restore. Prefer update_cost → Skipped to just exclude. Not on Posted. A refusal carries retryable (+ retry_after seconds while the record is still processing).

konto_create_cost vs konto_create_cost_adv: file → OCR path vs. you-have-the-numbers path. The OCR path invokes Google Document AI (a metered service); use _adv when you already have the figures.

konto_create_cost_adv — required: date, amount, how_paid (1–4), supplier_name, supplier_id (kennitala), type (cost code). Optional: description, vat_11 / vat_24 (VAT amounts in ISK, not rates), credit_note (true = refund; keep the amount positive), optional file attachment.

{
  "date": "2026-06-15", "amount": 12400, "how_paid": 3,
  "supplier_name": "Múlakaffi ehf", "supplier_id": "5512871499",
  "type": "2353", "vat_24": 2400
}

Tasks & time tracking — task

Tool Purpose
konto_list_tasks List by type: open / invoice / older.
konto_count_tasks Count by type.
konto_get_task One task in full — includes its time-log entries, each with the task-LOG GUID needed by edit/delete.
konto_create_task Create a task linked to a customer, with an item.
konto_start_task Start the timer.
konto_end_task Stop the running timer (optional note). Only stops the timer — doesn't archive or add a dated entry.
konto_log_task Manually log dated hours against a task. Also stops a running timer.
konto_edit_task_log Edit an existing task-log entry.
konto_deactivate_task Archive a task (removes it from the open list).
konto_delete_task_log Delete a task-log entry (irreversible).

GUID gotcha: konto_log_task takes the task's own GUID (from list_tasks). konto_edit_task_log / konto_delete_task_log take a task-LOG entry GUID (from get_task's log list). They are different ids — mixing them up is the most common task error.

konto_create_task — required: customer_guid, name. Item fields default: item_uom → KGS, item_tax → AA (11%), item_unit_price → "0". Set them for hourly work (item_uom: "HUR", item_tax: "S", a real price).

Product sales — sell_product (read-only)

Selling pages are created/managed in the Konto web UI; the API only reads them.

Tool Purpose
konto_list_product_sales List selling pages, newest first. type is an integer: 0 standard, 1 subscription, 2 donation, 3 coupon, 4 event.
konto_count_product_sales Count, optional search_text.
konto_list_product_sale_attendees Ticket buyers for one event sale (type 4, by guid). Other types are refused.

See also