Se você quer conectar um agente, aplicação ou ferramenta própria ao MCP da Salvy, esta página reúne os requisitos técnicos e o catálogo das ferramentas disponíveis.
A documentação principal explica o MCP de forma mais prática. Aqui você encontra os detalhes para quem precisa configurar, desenvolver ou validar uma integração.
Antes de começar
Para usar o MCP da Salvy, você precisa de:
- uma conta ativa na Salvy;
- acesso às empresas que deseja consultar ou gerenciar;
- um cliente ou aplicação compatível com MCP via Streamable HTTP;
- uma forma de autenticação válida;
- permissões para realizar as operações desejadas.
O MCP da Salvy está disponível em:
O endpoint utiliza Streamable HTTP e aceita requisições POST.
Compatibilidade
O MCP da Salvy utiliza o transporte Streamable HTTP, permitindo que clientes compatíveis com MCP se conectem diretamente ao servidor.
A implementação atual:
- utiliza
POST para comunicação com o servidor;
- não utiliza
stdio;
- não utiliza o transporte legado de
SSE;
- não mantém uma sessão entre requisições;
- não exige
Mcp-Session-Id.
A compatibilidade final também depende do cliente de IA ou aplicação utilizado para fazer a conexão.
Descoberta de ferramentas
Depois de autenticar, o cliente pode consultar as ferramentas disponíveis no servidor usando tools/list.
As ferramentas são organizadas em dois grandes grupos:
- Leitura: consulta de informações da operação da Salvy;
- Escrita: ações que alteram dados ou podem gerar efeitos na conta.
O servidor informa as ferramentas disponíveis, seus parâmetros e suas descrições para que o cliente possa decidir qual utilizar.
Importante
A disponibilidade de uma ferramenta na descoberta não significa que qualquer usuário possa executá-la.
Autenticação, permissões e regras da operação são verificadas quando a ferramenta é chamada.
Catálogo de ferramentas
Se você quer saber exatamente o que o MCP da Salvy pode fazer, este é o lugar.
Leitura
Escrita
Operações em lote
Algumas ferramentas do MCP da Salvy permitem realizar uma mesma operação em várias linhas de uma só vez.
Os limites variam de acordo com a ferramenta:
Criação de linhas
- Limite por chamada: até 50 linhas.
- Cota por empresa: até 50 linhas em uma janela de 24 horas.
- Disponibilidade: a criação depende das condições de habilitação do MCP para a empresa.
Atualização de linhas
- Limite por chamada: até 50 linhas.
- Campos atualizáveis: nome, centro de custo, colaborador, grupo e campos personalizados.
- Nome da linha: até 60 caracteres.
- Atualização parcial: somente os campos informados são alterados. O envio de
null permite limpar um campo compatível com essa operação.
A ferramenta valida as linhas antes de iniciar as alterações. Depois dessa etapa, cada linha pode ter um resultado individual: aplicada, já estava no estado solicitado ou falhou.
Adição de dados
- Limite por chamada: até 25 linhas.
- Limite de dados: até 10 GB.
Alteração de plano
- Limite por chamada: até 25 linhas.
Cancelamento de linhas
- Limite por chamada: até 25 linhas.
Desagendamento de cancelamento
- Limite por chamada: até 25 linhas.
Bloqueio e desbloqueio
- Bloqueio: até 50 linhas por chamada.
- Desbloqueio: até 50 linhas por chamada.
Como funciona o processamento
Cada ferramenta possui suas próprias regras de validação e processamento. Por isso, uma operação em lote pode ter resultados diferentes para cada linha.
Em algumas operações, todas as linhas são validadas antes de qualquer alteração ser aplicada. Depois dessa validação, porém, cada linha pode ser processada individualmente, e uma falha em uma delas não significa necessariamente que as demais alterações serão desfeitas.
O resultado pode indicar quais linhas foram atualizadas, quais já estavam no estado solicitado e quais não puderam ser processadas.
ImportanteNão considere uma operação concluída integralmente apenas porque a solicitação foi aceita. Confira o resultado retornado pelo agente e, quando necessário, consulte o estado final da operação.
Resultados e estados
As ferramentas do MCP da Salvy podem retornar diferentes resultados, de acordo com o tipo de operação e o estado dos dados consultados.
Uma solicitação aceita não significa necessariamente que a operação foi concluída. Por exemplo, uma operação pode ter sido agendada ou continuar em processamento.
Como interpretar os resultados
Entre os resultados possíveis, estão:
- Operação aplicada: a alteração foi realizada.
- Operação já aplicada: o estado solicitado já havia sido alcançado.
- Operação agendada: a execução foi programada para outro momento.
- Resultado indisponível: não há dados disponíveis para o período ou a consulta solicitada.
- Falha na operação: a ação não pôde ser concluída.
Os estados disponíveis variam conforme a ferramenta. Em operações realizadas sobre várias linhas, também pode haver resultados diferentes para cada linha processada.
Consultar o resultado de uma operação
Algumas operações são assíncronas: a solicitação é aceita, mas o resultado final fica disponível posteriormente.
Ao consultar o resultado, verifique se a operação foi concluída e se houve linhas que não puderam ser processadas. Se necessário, utilize essas informações para decidir os próximos passos, evitando repetir uma ação que já tenha sido executada.
Para desenvolvedores
Se você está construindo uma integração própria, recomendamos começar por:
- conectar ao endpoint do MCP;
- configurar a autenticação;
- executar
tools/list;
- selecionar uma ferramenta de leitura;
- validar os parâmetros e o formato do resultado;
- só depois habilitar operações de escrita.
Para uma primeira integração, prefira começar com ferramentas de consulta. Isso permite validar autenticação, descoberta e interpretação dos resultados antes de introduzir operações que alteram dados ou geram cobrança.
Referência rápida
