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 (email optional). Delivery 3/2 means Konto emails/sends the invoice to the customer when one is issued.

Accounting status (`accounting_status`)¶

Invoices (update_invoice): Created, Posted, Skipped, Error.
Costs (update_cost): Created, Posted, Skipped, Error. New is not settable here — reach it via konto_reopen_cost. Posted is terminal (exported to accounting, locked; can't be edited or deleted).

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/search (`search` matches name, kennitala, or email), paginated.
`konto_count_customers`	Count, optional `search`.
`konto_get_customer`	One customer in full by `guid`.
`konto_create_customer`	Create. Returns the new customer + GUID.
`konto_update_customer`	Update; send only the fields to change (fetch first to preserve others).

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, lang (is/en, default is), currency (default ISK), country (default IS). email is required unless delivery=4.

{ "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.
`konto_update_item`	Update; send fields to change (`active: "0"` deactivates).

konto_create_item — required: description, unit_price (numeric string, dot-decimal, e.g. "1990.00"). Optional: uom (default C62), tax (⚠️ default Z = 0% — set S or AA for taxable items), category, active (default "1").

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

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 or quote.
`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/quote), 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). Oldest-first — pass `from_date` for "recent". 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 (+ message).
`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`	Permanent delete (irreversible). Prefer `update_cost → Skipped` to just exclude. Not on Posted.

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. Each carries a type: `STAND` / `SUB` / `DONA` / `EVENT`.
`konto_count_product_sales`	Count, optional `search_text`.
`konto_list_product_sale_attendees`	Ticket buyers for one EVENT sale (by `guid`). STAND/SUB/DONA have none.

Konto MCP — Tool & API reference¶

Conventions¶

Scopes at a glance¶

Shared value sets — the write contract¶

Tax codes (tax)¶

Units of measure (uom)¶

Cost codes (type on costs)¶

Payment method (how_paid, costs)¶

Invoice delivery (delivery, customers → server output_select)¶

Accounting status (accounting_status)¶