MCP-palvelin

Nordlet tarjoaa Model Context Protocol -rajapinnan osoitteessa https://api.nordlet.com/mcp. Siihen yhdistetty tekoälyavustaja voi hakea rajapinnasta tietoja, lukea minkä tahansa toiminnon pyyntökaavion ja kutsua sitä samalla API-avaimella, yrityksellä ja käyttöoikeuslaajuuksilla (scopes) kuin suorassa pyynnössäkin. Jokainen työkalukutsu on tavallinen API-pyyntö: se todennetaan, sille asetetaan pyyntörajat (rate limit) ja sen käyttöä mitataan kuten tavallistakin pyyntöä, ja tietoja muuttava kutsu päivittää yrityksen kirjanpitoa.

Yhteyden muodostaminen

Päätepiste käyttää Streamable HTTP -protokollaa, ja sen todentamiseen käytetään Aloitusoppaasta saatavaa Bearer API -avainta. Claude Codessa:

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

Mikä tahansa muu MCP-asiakasohjelma käyttää samaa URL-osoitetta ja otsikkoa. Avain, jonka laajuus on rajoitettu arvoon *:read, voi kutsua vain lukutoimintoja. Työkalut ilmoittavat puuttuvasta käyttöoikeuslaajuudesta rajapinnan 403-virheellä.

Työkalut

Kolme työkalua kattavat rajapinnan kaikki toiminnot:

Työkalu	Mitä se tekee
search_operations	Etsii toimintoja niiden nimessä, polussa, yhteenvedossa tai kuvauksessa olevien sanojen perusteella, valinnaisesti tietyn moduulin (sales, bank, reports jne.) sisällä. Ilman hakutermiä se listaa moduulit.
describe_operation	Palauttaa yhden toiminnon metodin, polun, kuvauksen ja JSON-pyyntökaavion; includeResponse: true lisää mukaan 200-vastauksen kaavion.
call_operation	Suorittaa yhden toiminnon JSON-rungolla. Vastausrunko palautetaan JSON-muodossa; 4xx- tai 5xx-vastaus palautetaan työkaluvirheenä, joka sisältää tilakoodin ja virhekehyksen. Valinnainen idempotencyKey lähetetään Idempotency-Key-otsikkona, jolloin samaa avainta käyttävä toistettu kutsu palauttaa ensimmäisen vastauksen uudelleen sen vaikutuksen toistamisen sijaan.

Eniten käytetyt toiminnot ovat myös suoria työkaluja omilla pyyntökaavioillaan, joten avustaja näkee niiden kentät ilman erillistä hakua: 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 ja reports_debt_aging. Jokaisella työkalulla on MCP-huomautukset (readOnlyHint, destructiveHint), jotka kertovat asiakasohjelmalle, kirjoittaako työkalu tietoja.

Toimintojen hakemisto ja kaavotukset generoidaan samasta OpenAPI-kuvauksesta kuin rajapinnan viitetiedot ja SDK:t, joten rajapintaan lisätty toiminto näkyy search_operations-haussa sen julkaisun yhteydessä. Palvelimen ohjeet muistuttavat avustajaa käytännöistä: summat ovat desimaalimerkkijonoja, listoissa käytetään parametreja page, pageSize, sort ja filter, ja maakohtainen ilmoittaminen palauttaa virheen 422, jos yritys sijaitsee kyseisen maan ulkopuolella.