MCP — connect an AI agent — SLK Invoices API

SLK Invoices runs a remote Model Context Protocol server, so Claude Code, Claude Desktop, Cursor or any MCP client can search your documents and customers, pull reports, and draft or issue documents — using the same API key as the REST API.

The full guide (client configuration, the stdio bridge for Claude Desktop, error handling) is docs/mcp.md. This page is the summary.

Endpoint#

POST https://invoice.slk.co.il/api/mcp
Authorization: Bearer <your API key>      (X-Api-Key also works)

JSON-RPC 2.0, MCP protocol 2025-06-18, Streamable HTTP: one message in, one JSON message out. There is no SSE stream: GET /api/mcp answers 405.
Batched JSON-RPC arrays are rejected. Notifications (no id) get 202 Accepted with no body.
Auth and tenancy are identical to the REST API: the key selects the business and the request runs inside its isolated database. The 600 requests/minute per-key limit is shared with the REST API.

Connect#

bash

claude mcp add --transport http slk-invoices https://invoice.slk.co.il/api/mcp \
  --header "Authorization: Bearer <your API key>"

Cursor (.cursor/mcp.json):

json

{ "mcpServers": { "slk-invoices": { "url": "https://invoice.slk.co.il/api/mcp", "headers": { "Authorization": "Bearer <your API key>" } } } }

Claude Desktop only launches local servers: download the zero-dependency bridge with curl -o mcp-stdio.mjs https://invoice.slk.co.il/api/mcp/stdio-bridge and point the client at it (see docs/mcp.md).

Claude app / claude.ai / ChatGPT — no API key, 2 clicks#

Those clients cannot send an Authorization header, so use the AI connector URL instead: /billing/settings → "חיבור ל-AI" → חיבור copies a ready URL of the form https://invoice.slk.co.il/api/mcp/c/ac_…. Add it in claude.ai → Settings → Connectors → Add custom connector with authentication None (works on the Claude mobile app too, with voice), or in ChatGPT → Settings → Connectors (Developer mode). The parsing runs on your own Claude / ChatGPT subscription; SLK Invoices spends no AI tokens. ניתוק on the same card revokes the URL immediately and never touches your website API key.

Tools#

Tool	Access	Does
`search_documents`	read	Filter issued documents by type, status, dates, customer or free text.
`get_document`	read	One full document by id, or by number + type.
`list_customers`	read	Search customer cards.
`get_customer`	read	A customer plus a statement summary (balance, open documents, recent documents).
`search_items`	read	Search the item/price catalogue.
`income_summary`	read	Income for a period by document type, with VAT and counts.
`open_invoices`	read	Unpaid invoices with 0-30 / 31-60 / 61-90 / 90+ day ageing.
`calculate`	read	Dry-run totals for a document that does not exist yet.
`create_draft_document`	write	Creates a draft only — never issues, never numbers.
`issue_document`	write	Issues an existing draft (numbers and freezes it). Requires `confirm_total_agorot` equal to the draft's total.

Issuing is deliberately two steps, so an agent can prepare a document and a human (or a second explicit call) decides when it becomes a numbered, immutable fiscal document. Money in tool inputs and outputs is integer agorot, exactly like the REST API; input schemas are served live by tools/list.

Read tools work while the account is dormant; the two write tools are refused until billing is enabled. Issuing through MCP passes the same plan gates as the REST API (api_write, monthly quota) and fires the same document.issued webhook.

In a sandbox account issue_document is refused (so no real numbered document can exist); drafts and all read tools work.

Minimal request#

http

POST /api/mcp
Authorization: Bearer bk_…
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

A tool that fails at runtime (validation, dormant module, not found) returns HTTP 200 with result.isError: true and the reason in result.content[0].text; transport problems use HTTP errors: 401 (JSON-RPC -32001), 429 (-32000), 400 (-32700), unknown method -32601, unknown tool -32602.