MCP server — úvod a tools

Co je MCP

Model Context Protocol je standard od Anthropic pro propojení LLM klientů (Claude Desktop, Cursor, vlastní agent) s vašimi systémy.

Transport

Ponk CRM MCP server používá stdio transport — spustí se jako lokální proces, který klient (např. Claude Desktop) ovládá přes stdin/stdout. Pro připojení potřebujete API token typu mdk_*, který získáte v CRM v sekci Nastavení → API klíče.

Read tools

Všechny tools mají prefix crm_:

• crm_list_jobs — seznam zakázek (filtry: state, dateFrom, dateTo, customerId)
• crm_get_job — detail zakázky podle code (např. P-260042)
• crm_search_customers — vyhledání zákazníka podle jména / e-mailu / telefonu
• crm_get_inventory_report — agregovaný stav skladu
• crm_list_stock — položky skladu s filtrováním
• crm_list_invoices — seznam faktur
• crm_get_invoice — detail faktury
• plus ~70 dalších read tools (kalendář, statistiky, e-maily, SMS historie)

Draft tools (vyžadují schválení v CRM)

Změny jsou navrženy, ale aplikují se až po vašem potvrzení v CRM UI:

• crm_update_job_state — návrh změny stavu zakázky
• crm_send_sms — návrh SMS k odeslání
• a další draft akce

Write tools (přímý zápis)

• crm_add_job_note — přidání poznámky k zakázce
• a další drobné write operace

Per-user oprávnění

Token je per-uživatel a dědí jeho roli. Role v CRM jsou: ADMIN, TECHNICIAN, ASSISTANT, ACCOUNTANT, VIEWER. Každá má omezený přístup — např. VIEWER nemůže volat write tools, ACCOUNTANT nevidí interní SMS automatizace. Detaily v matrix v sekci User roles.

Audit log

Každé volání MCP přes API token se loguje do ApiKeyAuditLog — kdo, kdy, jaký tool, výsledek, doba. Retence 90 dní.

Připojení v Claude Desktop

Stdio MCP server vyžaduje příkaz, který klient spustí. Konkrétní příkaz a env proměnné vám předáme při onboarding. Vzor:

{
  "mcpServers": {
    "ponk-crm": {
      "command": "node",
      "args": ["/cesta/k/ponk-mcp-server/dist/index.js"],
      "env": {
        "CRM_API_URL": "https://crm.vase-domena.cz",
        "CRM_API_TOKEN": "mdk_xxx_yyy"
      }
    }
  }
}

HTTP/SSE remote varianta MCP serveru je na roadmapě.