MCP сървър

Nordlet поддържа протокола Model Context Protocol на адрес https://api.nordlet.com/mcp. Свързан към него AI асистент може да търси в API, да чете схемата на заявките за всяка операция и да я извиква, използвайки същия API ключ, компания и обхвати (scopes) като при директна заявка. Всяко извикване на инструмент представлява обикновена API заявка: тя се автентикира, следи се за ограничение на заявките (rate limiting) и се отчита като такава, а операция, която променя данни, отразява промените в счетоводството на компанията.

Свързване

Крайната точка (endpoint) работи със Streamable HTTP и се автентикира с Bearer API ключ от Първи стъпки. В Claude Code:

claude mcp add --transport http nordlet https://api.nordlet.com/mcp --header "Authorization: Bearer nl_..."

Всеки друг MCP клиент използва същия URL адрес и хедър. Ключ с обхват *:read може да извиква само операции за четене, като инструментите докладват липсващ обхват като грешка 403 на API.

Инструменти

Три инструмента покриват всяка операция на API:

Инструмент	Какво прави
search_operations	Намира операции по думи в тяхното име, път, резюме или описание, по избор в рамките на определен модул (sales, bank, reports, ...). Без заявка за търсене извежда списък с модулите.
describe_operation	Връща метода, пътя, описанието и JSON схемата на заявката за дадена операция; параметърът includeResponse: true добавя схемата на отговора 200.
call_operation	Изпълнява една операция с JSON тяло. Тялото на отговора се връща като JSON; отговор с код 4xx или 5xx се връща като грешка на инструмента заедно с кода на състоянието и обвивката за грешки. Незадължителен параметър idempotencyKey се изпраща като хедър Idempotency-Key, така че повторно извикване със същия ключ връща първоначалния отговор, вместо да изпълнява действието отново.

Най-използваните операции са достъпни и като директни инструменти със собствени схеми за заявки, така че асистентът вижда техните полета без необходимост от допълнително търсене: partners_list, partners_get, partners_create, partners_find_or_create, catalog_items_list, sales_invoices_list, sales_invoices_get, sales_invoices_create, sales_invoices_issue, sales_invoices_send, purchases_invoices_list, purchases_invoices_create, purchases_invoices_register, bank_transactions_list, bank_transactions_import, bank_transactions_match, ledger_journal_transactions_list, reports_trial_balance, reports_financial_statements, reports_vat_summary и reports_debt_aging. Всеки инструмент съдържа MCP анотации (readOnlyHint, destructiveHint), които указват на клиента дали операцията записва данни.

Индексът на операциите и схемите се генерират от същата OpenAPI дефиниция като API справката и SDK пакетите, така че операция, добавена към API, се появява в search_operations с пускането на съответната версия. Инструкциите на сървъра напомнят на асистента основните конвенции: сумите са десетични низове (decimal strings), списъците използват параметрите page, pageSize, sort и filter, а справка за подаване на данни по държави връща грешка 422 за компания извън съответната държава.