LoadSnap

Referência do servidor MCP

Tudo o que é necessário para conectar um assistente de IA a uma conta LoadSnap, e o que ele pode ler uma vez conectado.

Endpoint

https://app.loadsnap.co.uk/api/mcp

Um servidor remoto do Model Context Protocol usando o transporte HTTP Streamable: JSON-RPC 2.0 sobre um único POST. O servidor não tem estado, portanto não há cabeçalho de sessão nem fluxo de eventos iniciado pelo servidor, e um GET retorna 405.

Adicione-o ao Claude, Claude Code, ChatGPT, Cursor ou qualquer outro cliente compatível com MCP como um conector personalizado ou remoto, usando essa URL. Não há chave de API para colar.

Autenticação

OAuth 2.1: código de autorização com PKCE, além de Registro Dinâmico de Cliente, para que um cliente se cadastre sozinho sem configuração manual. A descoberta funciona da maneira usual: uma solicitação não autenticada retorna 401 com um cabeçalho WWW-Authenticate apontando para os metadados do recurso protegido.

Metadados do recurso protegido	/.well-known/oauth-protected-resource
Metadados do servidor de autorização	/.well-known/oauth-authorization-server
Registro dinâmico de cliente	/api/oauth/register
Autorização	/oauth/authorize
Token	/api/oauth/token

A pessoa faz login na LoadSnap e aprova a conexão em uma tela que nomeia o cliente e a organização dele. Os tokens de acesso duram uma hora e são renovados com um token de atualização, para que a conexão continue funcionando sem novo login.

O acesso é autorizado como pessoa, não como chave. A associação à organização e o plano são verificados novamente a cada solicitação; portanto, remover alguém de uma organização encerra o acesso do conector dessa pessoa junto.

Escopo do acesso

Cada consulta é rigorosamente filtrada para a organização do usuário autorizado, resolvida no lado do servidor a partir do token. O cliente nunca fornece uma organização, portanto não pode solicitar dados de outra empresa. A segurança em nível de linha aplica a mesma fronteira no banco de dados subjacente.

15 das 21 ferramentas apenas leem. As 6 cujos nomes começam com create_ adicionam um registro e nada mais: nenhuma edita, exclui, envia arquivos à DEFRA, assina uma nota de transferência, emite uma fatura ou concede um login de escritório. Cada uma é marcada como de escrita em suas anotações, para que um cliente peça permissão à pessoa antes de executá-la.

A única exceção ao escopo da organização é find_waste_codes, que pesquisa o Catálogo Europeu de Resíduos publicado — a mesma lista nacional para todos, e não os dados de ninguém.

Ferramentas

21 ferramentas, cada uma com escopo para a organização autorizada. Cada uma está listada abaixo com a descrição que um cliente recebe e os argumentos que aceita. Uma ferramenta marcada como writes adiciona um registro; as demais apenas leem.

find_movements

Encontrar movimentos de resíduos

Listar ou pesquisar os registros de movimentos de resíduos desta organização (Notas de Transferência de Resíduos) e trabalhos, por nome do produtor, cliente ou transportador e/ou intervalo de datas de coleta. Use isto para 'fizemos movimentos para X', 'o que coletamos de Y em maio' ou 'o que movemos na semana passada' sem nenhum nome.

name	opcional	Nome do produtor, cliente ou transportador para pesquisar. Omita para listar tudo no intervalo de datas.
date_from	opcional	Limite inferior opcional em data ISO (AAAA-MM-DD)
date_to	opcional	Limite superior opcional em data ISO (AAAA-MM-DD)

find_receipts

Encontrar recibos de recebimento

Listar ou pesquisar os recibos de recebimento desta organização (resíduos que chegam ao próprio local) por nome do transportador ou produtor e/ou intervalo de datas de recebimento. Omita o nome para listar tudo o que foi recebido no intervalo.

name	opcional	Nome do transportador ou produtor. Omita para listar tudo.
date_from	opcional	Limite inferior opcional em data ISO (AAAA-MM-DD)
date_to	opcional	Limite superior opcional em data ISO (AAAA-MM-DD)

count_movements

Contar movimentos de resíduos

Contar os movimentos de resíduos desta organização em um intervalo de datas e totalizar o peso, opcionalmente dividido entre entrada ou saída. Use isto para 'quantas cargas fizemos no mês passado', 'quanto resíduo movimentamos este ano', 'quantas coletas esta semana'. Conta por data de coleta.

date_from	opcional	Limite inferior em data ISO (AAAA-MM-DD) na data de coleta
date_to	opcional	Limite superior em data ISO (AAAA-MM-DD) na data de coleta
direction	opcional	inbound = resíduos recebidos no próprio local da organização, outbound = resíduos que o caminhão dela levou ou enviou. Omita para todos.

defra_filings

Envios à DEFRA

Contar e listar os envios de rastreamento de resíduos desta organização à DEFRA em um intervalo de datas, e listar os registros ainda aguardando envio. Use isto para 'quantos envios à DEFRA fizemos esta semana', 'algo falhou com a DEFRA', 'o que ainda está pendente'.

date_from	opcional	Limite inferior em data ISO (AAAA-MM-DD) na data do envio
date_to	opcional	Limite superior em data ISO (AAAA-MM-DD) na data do envio
include_outstanding	opcional	Também retornar os registros que ainda não foram enviados à DEFRA. O padrão é true.

find_parties

Encontrar transportadores e locais

Resolver um nome de empresa ou local para os transportadores e locais conhecidos da organização.

name	obrigatório	Nome da empresa ou local

find_jobs

Encontrar trabalhos agendados

Listar ou pesquisar os trabalhos desta organização — trabalho reservado, em andamento ou concluído — por nome do cliente e/ou intervalo de datas agendadas. Use isto para 'o que faremos amanhã', 'o trabalho da Carter está reservado', 'o que ainda não foi alocado'. Lê a partir da data mais antiga, porque uma lista de trabalhos é uma agenda.

name	opcional	Nome do cliente para pesquisar. Omita para listar tudo no intervalo.
status	opcional	Status do trabalho para filtrar, por exemplo draft, scheduled, in_progress, completed, cancelled.
date_from	opcional	Limite inferior opcional em data ISO (AAAA-MM-DD)
date_to	opcional	Limite superior opcional em data ISO (AAAA-MM-DD)

find_invoices

Faturas e valores devidos

Listar as faturas desta organização e totalizar o que ainda é devido, opcionalmente apenas as não pagas. Use isto para 'quem nos deve dinheiro', 'quanto está pendente', 'a fatura da Carter foi paga', 'o que está vencido'. Os totais estão na moeda da fatura.

name	opcional	Nome da empresa para a qual a fatura foi emitida. Omita para listar tudo no intervalo.
status	opcional	Status da fatura para filtrar, por exemplo draft, issued, paid, void.
only_unpaid	opcional	Apenas faturas com saldo ainda a pagar. O padrão é false.
date_from	opcional	Limite inferior opcional em data ISO (AAAA-MM-DD)
date_to	opcional	Limite superior opcional em data ISO (AAAA-MM-DD)

find_vehicles

Veículos e sua documentação

Listar os veículos desta organização com o vencimento de MOT, imposto e seguro, e sinalizar qualquer um que tenha expirado. Use isto para 'o que está na frota', 'algo está sem MOT', 'quando vence o imposto do VX19 ABC'. MOT e imposto vêm da DVLA e são tão atuais quanto a última verificação.

name	opcional	Registro ou descrição para pesquisar. Omita para listar tudo no intervalo.
include_inactive	opcional	Também retornar veículos retirados da frota. O padrão é false.

find_people

A equipe e o que cada um pode usar

Listar as pessoas na equipe desta organização e quais das três formas de acesso cada uma possui: um login de escritório, o aplicativo do motorista, o aplicativo da balança. Use isto para 'quem dirige para nós', 'o Dave tem o aplicativo do motorista', 'quem está na equipe'.

name	opcional	Nome ou e-mail da pessoa para pesquisar. Omita para listar tudo no intervalo.
drivers_only	opcional	Apenas pessoas que possuem o aplicativo do motorista. O padrão é false.

compliance_status

Certificados, licenças e registros

Listar os certificados, licenças e registros que esta organização tem registrados, com suas datas de validade, e informar quais já expiraram. Use isto para 'nosso registro de transportador de resíduos ainda é válido', 'o que vence este ano', 'temos um certificado ISO arquivado'.

expired_only	opcional	Apenas os que já expiraram. O padrão é false.

find_documents

Encontrar um documento

Encontrar os documentos armazenados desta organização — notas de transferência de resíduos, notas de remessa, licenças, documentação enviada — por tipo e/ou data, com um link para cada um. Use isto para 'envie-me a nota de transferência daquela carga', 'que documentação temos sobre este trabalho'.

document_type	opcional	Tipo de documento para filtrar, por exemplo wtn, hwcn, annex_vii, permit, upload.
movement_id	opcional	Apenas documentos anexados a este movimento de resíduos.
job_id	opcional	Apenas documentos anexados a este trabalho.
date_from	opcional	Limite inferior opcional em data ISO (AAAA-MM-DD)
date_to	opcional	Limite superior opcional em data ISO (AAAA-MM-DD)

container_stock

Caçambas e contêineres

Quais contêineres esta organização possui e onde estão: os rastreados individualmente com número de ativo e estado, e os tipos mantidos como total contínuo. Use isto para 'quantas caçambas de 8 jardas temos livres', 'onde está a caçamba 214', 'o que está alugado'.

container_type	opcional	Tipo de contêiner para filtrar, por exemplo skip, roro, bin.
container_size	opcional	Tamanho do contêiner para filtrar, por exemplo 8yd.
state	opcional	Estado de um contêiner rastreado individualmente, por exemplo in_yard, on_site, in_transit.

find_contracts

Contratos e passes de temporada

Listar os acordos permanentes desta organização: contratos e passes de temporada, quais resíduos cada um cobre, as datas de vigência e se ambos os lados assinaram. Use isto para 'o que temos sob contrato', 'o passe de temporada foi assinado', 'o que vence este mês'.

site_id	opcional	Apenas acordos para este local.
active_only	opcional	Apenas acordos ainda em vigor. O padrão é false.

consignee_returns

Declarações trimestrais de destinatário

As declarações trimestrais de destinatário desta organização para resíduos perigosos recebidos: o trimestre, o que vence quando, quantas remessas e qual peso, e se foi enviado. Use isto para 'nossa declaração de destinatário está feita', 'o que vence neste trimestre'. Apenas para receptores; um transportador não tem nenhuma.

quarter	opcional	Um rótulo de trimestre, por exemplo "Q1 2026".
status	opcional	Status para filtrar: not_started, generated, reviewed ou submitted.

find_waste_codes

Consultar um código de resíduo

Pesquisar o Catálogo Europeu de Resíduos (EWC) por código ou pelo que o resíduo é, e informar se cada código é perigoso ou uma entrada de espelho. Use isto para 'qual código é o gesso', '17 05 03 é perigoso'. Esta é a lista nacional publicada, não os dados próprios da organização.

query	obrigatório	Um código ou parte dele ("17 05"), ou palavras que descrevam o resíduo ("gesso").
hazardous_only	opcional	Apenas códigos perigosos. O padrão é false.

create_customer

Adicionar um clientewrites

Adicionar um cliente (um local de coleta do qual a organização coleta resíduos). Responde com o que ainda é necessário se algo obrigatório estiver faltando, e não escreve nada. Se um cliente com esse nome e código postal já existir, retorna esse em vez de criar um segundo.

name	obrigatório	A empresa ou pessoa a quem o resíduo pertence
address	obrigatório	Onde o resíduo é coletado
postcode	obrigatório	Código postal do endereço de coleta
producer_type	opcional	Se o resíduo vem de uma empresa ou de uma residência. O padrão é business.
contact_name	obrigatório	Com quem falar no local
contact_email	opcional	O endereço de e-mail da pessoa
contact_phone	opcional	O número de telefone da pessoa
sic_code	opcional	O código SIC do produtor, se conhecido

create_receiving_site

Adicionar um local de recebimentowrites

Adicionar um local de recebimento (um depósito, estação de transferência ou instalação de reciclagem para onde os resíduos são levados). Responde com o que ainda é necessário se algo obrigatório estiver faltando, e não escreve nada.

nome	obrigatório	O nome do site
endereço	obrigatório	O endereço do site
código postal	obrigatório	Código postal do site
número_de_licença	opcional	Número de licença ambiental ou de isenção
nome_do_contato	opcional	Com quem falar no portão
email_do_contato	opcional	O endereço de email deles
telefone_do_contato	opcional	O número de telefone deles
é_site_próprio	opcional	Verdadeiro apenas se for o site próprio da organização, em vez de ser de outra pessoa. O padrão é falso.

create_carrier

Adicionar um transportador ou corretor

Adiciona um transportador, corretor ou revendedor com quem a organização trabalha. Responde com o que ainda é necessário se algo obrigatório estiver faltando e não escreve nada.

nome_da_empresa	obrigatório	O nome da empresa do transportador ou corretor
número_de_registro	opcional	O número de registro de transportador de resíduos deles, se conhecido
nome_do_contato	opcional	Com quem falar
email_do_contato	opcional	O endereço de email deles
telefone_do_contato	opcional	O número de telefone deles
endereço	opcional	O endereço deles
código postal	opcional	O código postal deles
anotações	opcional	Qualquer coisa que valha a pena registrar sobre eles

create_vehicle

Adicionar um veículo

Adiciona um veículo à frota. Responde com o que ainda é necessário se algo obrigatório estiver faltando e não escreve nada. Um registro já existente na frota retorna esse veículo em vez de criar um segundo.

registro	obrigatório	A placa
marca	opcional	Quem o fabricou
descrição	opcional	Modelo ou descrição
tipo_de_veículo	opcional	Que tipo de veículo é, por exemplo, caminhão de caçamba ou basculante
validade_do_mot	opcional	Quando o MOT expira (AAAA-MM-DD)
validade_do_imposto	opcional	Quando o imposto expira (AAAA-MM-DD)
peso_máximo_em_toneladas	opcional	Peso bruto em toneladas

create_driver

Adicionar um motorista

Adiciona um motorista, para que ele possa receber tarefas e assinar notas de transferência no aplicativo do motorista. Usa uma das permissões de motorista do plano e recusa se todas estiverem em uso. Não dá a ninguém um login de escritório: isso é distribuído na página de Equipe por um proprietário ou administrador. Alguém que já está na equipe recebe o aplicativo do motorista adicionado ao registro que já possui.

nome	obrigatório	O nome completo deles
email	obrigatório	O endereço de email deles, que é para onde vai o convite para o aplicativo do motorista
número_de_telefone	opcional	O número de telefone deles
função	opcional	O que eles fazem, por exemplo, motorista de HGV
endereço	opcional	O endereço residencial deles
código postal	opcional	O código postal residencial deles
validade_da_carteira	opcional	Quando a carteira deles expira (AAAA-MM-DD)
nome_do_contato_de_emergência	opcional	Quem chamar em uma emergência
telefone_do_contato_de_emergência	opcional	O número de telefone dessa pessoa

create_enquiry

Registrar uma solicitação de coleta

Registra uma solicitação de coleta (uma consulta) de um cliente, para que o escritório possa fazer uma cotação. Responde com o que ainda é necessário se algo obrigatório estiver faltando e não escreve nada.

nome_da_empresa	obrigatório	A empresa que está solicitando
nome_do_contato	obrigatório	Quem entrou em contato
email_do_contato	obrigatório	O endereço de email deles
telefone_do_contato	obrigatório	O número de telefone deles
endereço_do_site	obrigatório	Onde o resíduo está
código postal	opcional	Código postal desse endereço
descrição_do_resíduo	obrigatório	O que é o resíduo, nas palavras deles
tipo_de_serviço	opcional	O que eles estão pedindo, por exemplo, uma caçamba ou uma carga de garra
peso_estimado	opcional	Aproximadamente quanto, em toneladas
data_preferida	opcional	Quando eles gostariam (AAAA-MM-DD)
anotações_de_acesso	opcional	Qualquer coisa sobre como acessar o local

Escrita

As 6 ferramentas create_ adicionam um cliente, um site receptor, um transportador ou corretor, um veículo, um motorista e uma solicitação de coleta. Elas são como alguém insere dados no LoadSnap descrevendo-os em uma conversa, em vez de preencher um formulário ou preparar uma planilha.

Nada é escrito pela metade. Uma chamada que não tem algo obrigatório não escreve nada e responde com a lista do que ainda é necessário, formulada como perguntas, para que o assistente pergunte e chame novamente. Uma chamada para um registro que já existe devolve o registro que está lá em vez de criar um segundo, então executar a mesma solicitação duas vezes não pode deixar uma duplicata.

Um motorista adicionado dessa forma usa uma das permissões de motorista do plano e é recusado quando todas estão em uso, exatamente como na página de Equipe, e é comparado com as pessoas já na equipe, para que alguém que já trabalha lá receba o aplicativo do motorista adicionado ao registro que possui. Ninguém recebe um login de escritório: isso é um assento pago e um caminho para dentro do negócio, e é distribuído na Equipe por um proprietário ou administrador.

Arquivar para a DEFRA, assinar uma nota de transferência, emitir uma fatura e excluir qualquer coisa estão deliberadamente ausentes aqui. São coisas que uma pessoa faz no LoadSnap, com o nome dela nelas.

Painel interativo

O servidor publica um painel interativo como um recurso MCP em ui://loadsnap/panel, e todas as ferramentas apontam para ele. Um cliente que suporta a extensão de aplicativos desenha a resposta como um painel na conversa: uma tabela de registros, um cartão para o registro recém-adicionado ou uma lista de verificação do que ainda é necessário antes que algo possa ser salvo.

É um documento autossuficiente, sem dados próprios, sem token e sem nada buscado da rede. O cliente passa a resposta da ferramenta para ele. Toda ferramenta também retorna essa resposta como texto, então um cliente que não desenha painéis mostra exatamente o que sempre mostrou.

Limites e formatos

Pesos são retornados em quilogramas, a menos que um nome de campo diga toneladas. Datas estão no formato ISO (AAAA-MM-DD). Uma busca retorna as 25 correspondências mais relevantes; count_movements lê até 1.000 linhas e relata count_is_capped quando atinge esse teto, então um valor limitado nunca é apresentado como um total exato. O mesmo se aplica ao dinheiro devido em find_invoices, que relata totals_are_capped. Registros semeados como amostras são excluídos de todo resultado.

Requisitos

Uma conta LoadSnap no plano Pro ou superior e um login que pertença a uma organização LoadSnap. Todos que se conectam usam seu próprio login, porque a conexão é autorizada como eles.

Perguntas sobre o conector? Envie um email para info@loadsnap.co.uk, ou leia a visão geral do conector.