Servidor MCP

A Nordlet disponibiliza o Model Context Protocol em https://api.nordlet.com/mcp. Um assistente de IA ligado a este endpoint pode pesquisar a API, ler o esquema de pedido de qualquer operação e executá-la, utilizando a mesma chave de API, empresa e âmbitos (scopes) de um pedido direto. Cada chamada de ferramenta é um pedido de API comum: é autenticada, sujeita a limitação de taxa (rate limiting) e contabilizada como tal, e uma chamada de alteração modifica a contabilidade da empresa.

Ligar

O endpoint utiliza HTTP transmissível (Streamable HTTP) e é autenticado com a chave de API Bearer obtida em Guia de início. No Claude Code:

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

Qualquer outro cliente MCP aceita o mesmo URL e cabeçalho. Uma chave com âmbito limitado a *:read apenas pode executar operações de leitura; as ferramentas reportam um âmbito em falta como um erro 403 da API.

Ferramentas

Três ferramentas cobrem todas as operações da API:

Ferramenta	O que faz
search_operations	Encontra operações através de palavras no seu nome, caminho, resumo ou descrição, opcionalmente dentro de um módulo (sales, bank, reports, ...). Sem um termo de pesquisa, lista os módulos.
describe_operation	Devolve o método, o caminho, a descrição e o esquema de pedido JSON de uma operação; includeResponse: true adiciona o esquema da resposta 200.
call_operation	Executa uma operação com um corpo JSON. O corpo da resposta é devolvido em formato JSON; uma resposta 4xx ou 5xx é devolvida como um erro de ferramenta contendo o estado e o envelope de erro. Um parâmetro opcional idempotencyKey é enviado como o cabeçalho Idempotency-Key, permitindo que uma chamada repetida com a mesma chave reproduza a primeira resposta em vez de duplicar o efeito.

As operações mais utilizadas funcionam também como ferramentas diretas com os seus próprios esquemas de pedido, permitindo que o assistente consulte os respetivos campos sem necessidade de pesquisa prévia: 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 e reports_debt_aging. Cada ferramenta inclui as anotações do MCP (readOnlyHint, destructiveHint) que indicam ao cliente se a operação efetua gravações.

O índice de operações e os esquemas são gerados a partir da mesma descrição OpenAPI utilizada na Referência da API e nos SDKs, pelo que qualquer operação adicionada à API fica disponível em search_operations no momento do lançamento. As instruções do servidor recordam o assistente das convenções aplicáveis: os montantes são representados como cadeias de carateres decimais (decimal strings), as listagens utilizam page, pageSize, sort e filter, e as declarações fiscais específicas de um país respondem com o código 422 caso sejam aplicadas a uma empresa sediada noutro país.