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
claude mcp add tring --env TRING_API_KEY=kbl_test_... --env TRING_ISSUER_ID=... -- npx -y tring-mcp{
"mcpServers": {
"tring": {
"command": "npx",
"args": ["-y", "tring-mcp"],
"env": {
"TRING_API_KEY": "${TRING_API_KEY}",
"TRING_ISSUER_ID": "${TRING_ISSUER_ID}"
}
}
}
}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:
{
"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:
{
"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_KEY | Required. A sandbox key, kbl_test_... |
TRING_ISSUER_ID | The business the tools use when no issuer_id is given |
TRING_BASE_URL | The API address; default the sandbox. The local mock works too. |
TRING_MCP_ALLOW_LIVE | 1 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:
| Scope | Lets the agent |
|---|---|
read | Every list and read tool (events, webhook log, design), and the draft preview |
issue | tring_prepare_draft and tring_confirm_draft |
expenses | tring_attach_expense_receipt |
finance | tring_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
| Tool | Does | Changes anything |
|---|---|---|
tring_status | Environment, address, key id, default business | No |
tring_list_businesses, tring_get_business | Businesses this key may act for | No |
tring_list_documents, tring_get_document | Documents, with filters | No |
tring_list_customers, tring_get_customer | Customers | No |
tring_get_reference | VAT rate and allocation threshold | No |
tring_list_events | Events since a given id (document.issued, delivery.downloaded, ...) | No |
tring_list_webhook_endpoints, tring_list_webhook_deliveries | Webhook addresses and their delivery log, for debugging a receiver; never a secret | No |
tring_get_document_design | The design documents are produced with | No |
tring_prepare_draft | Computes a draft. Issues nothing. | Stores a draft |
tring_get_draft, tring_preview_draft | Reads a draft; writes its PDF preview to a private local file | No |
tring_attach_expense_receipt | Attaches 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 sent | Replaces the file in force |
tring_get_expense_receipt | Writes the receipt of an expense, byte for byte, to a private local file | No |
tring_confirm_draft | Issues the document | Yes, for good |
How issuing stays safe
- 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. - The person reads it and says yes.
- The agent calls
tring_confirm_draftwith thedraft_id, theapproved_totalandapproved_doc_typethe 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. - 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.