Tefter MCP

Remote MCP server for read-only Exchange and owner-local business data.

Endpoint

URL	`https://mcp.stage.tefter.com/mcp`
Transport	MCP Streamable HTTP, stateless, JSON responses. `POST` only.
Auth	`Authorization: Bearer tftk_…` — exactly one header, managed key with audience `mcp`.
Reachable	Only `/` and `/mcp` are routed from the internet.

1. Get a key

Sign in to the TX webapp as a MASTERADMIN of your organization.
Open Administracija organizacije → Moduli → Opšte, then enable MCP.
Open Kredencijali.
Create a service account with the scopes you need: orders:read for Exchange and Business order tools, traces:read for the Exchange trace tool, agreements:read for Exchange agreement tools, partners:read for customers, locations, and sales representatives, inventory:read for catalogues, articles, overlays, and warehouses, and audit:read for gated audit and publish-history sections.
Create a token under it with audience mcp and the same scopes.
Copy the key. It is shown once. Store it in an environment variable, for example TEFTER_MCP_KEY.

A key has one principal organization: the one that minted it. Exchange orders, traces, and agreements are visible only when that organization is both in the record ACL and an actual customer or supplier. Business orders and master data are owner-local and never accept an organization selector. Disable the organization's MCP module for an organization-wide shut-off, or revoke an individual key in Kredencijali.

2. Connect a client

opencode — opencode.json (project) or ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tefter": {
      "type": "remote",
      "url": "https://mcp.stage.tefter.com/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:TEFTER_MCP_KEY}" }
    }
  }
}

Claude Code:

claude mcp add --transport http tefter https://mcp.stage.tefter.com/mcp \
  --header "Authorization: Bearer ${TEFTER_MCP_KEY}"

3. Test it

List the tools your key can see:

curl -s https://mcp.stage.tefter.com/mcp \
  -H "Authorization: Bearer ${TEFTER_MCP_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Read one Exchange order (canonical order ID or the supplier's inbound document ID):

curl -s https://mcp.stage.tefter.com/mcp \
  -H "Authorization: Bearer ${TEFTER_MCP_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"tefter_get_exchange_order_detail","arguments":{"order_id":"<order-id>"}}}'

Read one owner-local inbound Business order (the direction argument is required):

curl -s https://mcp.stage.tefter.com/mcp \
  -H "Authorization: Bearer ${TEFTER_MCP_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"tefter_get_business_order_detail","arguments":{"direction":"inbound","order_id":"<order-id>"}}}'

Tools

Tool	Scope	What it returns
`tefter_get_organization`	none	The organization this key belongs to: identity, status, PIB, registration, contact and address fields, plus the credential behind the call: its service account ID, key ID, and scopes. Takes no arguments.
`tefter_find_exchange_orders`	`orders:read`	Exchange order discovery: a direct lookup by order ID, inbound document ID, or reference code, or a filtered window (counterparty, direction, location, status, issue kind, at most 31 days) over summaries, newest first, paginated.
`tefter_get_exchange_order_detail`	`orders:read`	One Exchange order from your organization's viewpoint: status, direction, pause reason, parties, and paginated article lines. Supplier-owned catalogue and overlay fields are returned only to that supplier.
`tefter_get_exchange_order_summary`	`orders:read`	Exchange aggregates over a period (at most 92 days): order counts per day, week, location, or status, and ordered quantities per article, with an optional comparison period. Day boundaries use Europe/Belgrade.
`tefter_find_business_orders`	`orders:read`	Owner-local Business order discovery. Required `direction` selects only the principal's `inbound_orders` or `outbound_orders`. Results are newest first in a half-open `createdAt` window (seven days by default, 31 days maximum), exclude archived rows by default, and return `TOO_BROAD` above the 3,000-document source bound. `include: totals` adds per-order line sums and `include: articles` adds the stored lines, so a window report needs no per-order detail calls.
`tefter_get_business_order_detail`	`orders:read`	One principal-owned Business order selected by required `direction` and ID. Returns a closed allowlist from the frozen stored snapshot; article pages default to 50 and max at 100, and a cursor becomes invalid when the order revision changes.
`tefter_get_exchange_order_trace`	`traces:read`	Exchange pipeline drill-down for one order: phases, pause reason, article-resolution counts, shared anomaly indicator, and split children. Detailed anomaly documents are customer-owner-only; ERP delivery details are supplier-owner-only. The audit section additionally requires `audit:read`.
`tefter_list_exchange_agreements`	`agreements:read`	The Exchange agreements where your organization is both ACL-listed and an actual customer or supplier.
`tefter_get_exchange_agreement`	`agreements:read`	One visible Exchange agreement's current policy configuration. The audit section additionally requires `audit:read` and returns the events your organization recorded.
`tefter_find_customers`	`partners:read`	List the principal organization's customers or select them by exact external reference or exact Serbian PIB.
`tefter_get_customer`	`partners:read`	One customer owned by the principal organization.
`tefter_list_customer_locations`	`partners:read`	Stored delivery locations embedded in one principal-owned customer record.
`tefter_list_sales_reps`	`partners:read`	Principal-owned sales-representative identity fields. Customer assignments and financial totals are not exposed.
`tefter_get_catalogue`	`inventory:read`	Your organization's own catalogue: identity and descriptive metadata.
`tefter_get_article`	`inventory:read`	Exact article lookup by ID or GTIN in your organization's own catalogue.
`tefter_get_overlay`	`inventory:read`	One overlay owned by your organization: state, base catalogue, and the effective entry set with overrides. The publish-history section additionally requires `audit:read`.
`tefter_list_warehouses`	`inventory:read`	Principal-owned warehouse identity, address, locality, and region fields.

If something fails

Response	Meaning
`401`	Key malformed, expired, revoked, wrong audience, or minted for another environment. The body is the same for all of these on purpose.
`403`	The principal organization's MCP module is disabled, or a browser `Origin` is not trusted. The module case returns `{"error":"mcp module disabled"}`; CLI clients send no `Origin`.
`400` header mismatch	`Mcp-Method` / `Mcp-Name` headers disagree with the JSON-RPC body. Remove or fix them.
`503`	The server could not reach a dependency. Retry shortly.
Only `tefter_get_organization` is listed	The key backs no other tool. Mint it with `orders:read`, `traces:read`, `agreements:read`, `partners:read`, or `inventory:read` per the tool table above. `audit:read` gates sections and registers no tool by itself.