Tring for developers עברית

AI agents and MCP

The Tring MCP server lets an AI coding agent (Claude Code, Cursor, any MCP client) read your documents and customers and prepare drafts. Issuing is a separate tool that refuses unless the person approved that exact draft.

Connect Claude Code

sh
claude mcp add tring --env TRING_API_KEY=kbl_test_... --env TRING_ISSUER_ID=... -- npx -y tring-mcp

With .mcp.json in the project, the key comes from your shell (${TRING_API_KEY}), so the file can be committed without it. Keep issuing behind a question in .claude/settings.json:

examples/claude-code/.claude/settings.json
{
  "permissions": {
    "allow": [
      "mcp__tring__tring_status",
      "mcp__tring__tring_list_businesses",
      "mcp__tring__tring_get_business",
      "mcp__tring__tring_list_documents",
      "mcp__tring__tring_get_document",
      "mcp__tring__tring_list_customers",
      "mcp__tring__tring_get_customer",
      "mcp__tring__tring_get_reference",
      "mcp__tring__tring_get_draft",
      "mcp__tring__tring_prepare_draft",
      "mcp__tring__tring_preview_draft",
      "mcp__tring__tring_get_expense_receipt"
    ],
    "ask": ["mcp__tring__tring_confirm_draft"]
  }
}

Connect Cursor

Save as .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project:

examples/cursor/mcp.json
{
  "mcpServers": {
    "tring": {
      "command": "npx",
      "args": ["-y", "tring-mcp"],
      "env": {
        "TRING_API_KEY": "${env:TRING_API_KEY}",
        "TRING_ISSUER_ID": "${env:TRING_ISSUER_ID}"
      }
    }
  }
}

Environment

Variable
TRING_API_KEYRequired. A sandbox key, kbl_test_...
TRING_ISSUER_IDThe business the tools use when no issuer_id is given
TRING_BASE_URLThe API address; default the sandbox. The local mock works too.
TRING_MCP_ALLOW_LIVE1 allows a production key. Without it a kbl_live_ key is refused and nothing is sent.

Key scopes

Every API key holds scopes, and every operation names the one it needs (the API reference shows it). Give the agent's key only what it needs:

ScopeLets the agent
readEvery list and read tool (events, webhook log, design), and the draft preview
issuetring_prepare_draft and tring_confirm_draft
expensestring_attach_expense_receipt
financetring_get_expense_receipt

A key with read alone keeps the agent read-only: a prepare answers 403 KEY_SCOPE_MISSING and nothing is done. Keys can also be limited to your networks (KEY_ADDRESS_NOT_ALLOWED otherwise).

Tools

ToolDoesChanges anything
tring_statusEnvironment, address, key id, default businessNo
tring_list_businesses, tring_get_businessBusinesses this key may act forNo
tring_list_documents, tring_get_documentDocuments, with filtersNo
tring_list_customers, tring_get_customerCustomersNo
tring_get_referenceVAT rate and allocation thresholdNo
tring_list_eventsEvents since a given id (document.issued, delivery.downloaded, ...)No
tring_list_webhook_endpoints, tring_list_webhook_deliveriesWebhook addresses and their delivery log, for debugging a receiver; never a secretNo
tring_get_document_designThe design documents are produced withNo
tring_prepare_draftComputes a draft. Issues nothing.Stores a draft
tring_get_draft, tring_preview_draftReads a draft; writes its PDF preview to a private local fileNo
tring_attach_expense_receiptAttaches the supplier's receipt (JPEG, PNG or PDF, from a local path or base64) to an expense; anything else by its first bytes is refused before it is sentReplaces the file in force
tring_get_expense_receiptWrites the receipt of an expense, byte for byte, to a private local fileNo
tring_confirm_draftIssues the documentYes, for good

How issuing stays safe

  1. The agent calls tring_prepare_draft. The answer is the draft in plain text (type, customer, lines, total) and the instruction to show it and ask.
  2. The person reads it and says yes.
  3. The agent calls tring_confirm_draft with the draft_id, the approved_total and approved_doc_type the person saw, and their words of approval. The server reads the draft again and refuses when the total or the type differ. Nothing is issued then.
  4. Confirming twice returns the same document. If the outcome is unknown, the tool says to confirm the same draft again, never to prepare a new one.

The tool's description tells the agent that it creates a legally binding tax document and may run only after the person approved the exact draft. The ask rule above makes Claude Code show you every call to it, whatever the agent decides.

The server never writes the key to a tool result or its log (anything that looks like a key is reduced to its public part), and writes previews only to a directory private to its process.

Prompts that work

  • "List the receipts we issued this week and their total."
  • "Prepare a receipt for order 1042: 350.00 by bank transfer from דנה כהן, customer ref crm-88. Show it to me before issuing."
  • "Write a Next.js route that issues a tax invoice / receipt after a successful payment, using tring-sdk, with the order id as the idempotency key."

Docs for agents

llms.txt is a short index with the rules an agent must keep; llms-full.txt is these docs as one file. Point your agent at them, or add to your project instructions (CLAUDE.md, .cursorrules):

Tring API docs: https://developers.tring.co.il/llms-full.txt
Use tring-sdk (TypeScript) or tring-sdk (Python, import tring_sdk). Prepare, show the draft, confirm only after approval.
One Idempotency-Key per document; after an unknown outcome confirm again, never prepare again.