Ferramentas MCP

O servidor MCP do muveya oferece dez ferramentas. Todas são somente leitura: cada uma é marcada com readOnlyHint: true e nenhuma pode criar, alterar ou aprovar nada. tools/list as devolve nesta ordem. O título é entregue no idioma solicitado.

Ferramenta	Título	Escopo da conexão OAuth	Permissão interna	Com OAuth
`clinics.list`	List clinics and warehouses	`inventory:read`	`inventory.read`	Funciona
`catalog.search`	Search the catalog	`catalog:read`	`catalog.read`	Funciona
`inventory.check`	Check stock availability	`inventory:read`	`inventory.read`	Funciona
`orders.get`	Get an order	`orders:read`	`orders.read.all`	Funciona
`approvals.list_pending`	List pending approvals	Nenhum	`approvals.decide`	Sempre recusada
`management.pending_decisions`	Pending management decisions	Nenhum	`approvals.decide`	Sempre recusada
`fulfillment.get_pick_list`	Get a pick list	Nenhum	`fulfillment.pick`	Sempre recusada
`analytics.consumption`	Consumption per supply	`analytics:read`	`reports.read`	Funciona
`management.briefing`	Management briefing	`analytics:read`	`reports.read`	Funciona
`management.compare_clinics`	Compare clinics	`analytics:read`	`reports.read`	Funciona

Como ler esta página

Escopo. A descrição de cada ferramenta, como um cliente a mostra, termina com uma frase como “Requires the inventory.read scope granted to this connection.” Esse nome é a permissão interna. A tabela acima a relaciona ao escopo da conexão OAuth que você deve pedir. A verificação acontece quando a ferramenta é chamada, antes de qualquer leitura; se o escopo faltar, a resposta é common.forbidden.
Argumentos. Todos os argumentos são opcionais, exceto os marcados como obrigatórios. Os argumentos são estritos: um nome que a ferramenta não declara (por exemplo tenantId ou clinicId) é recusado, assim como um valor fora dos limites indicados. Nenhuma ferramenta aceita um seletor de espaço de trabalho: ele sempre vem da conexão.
Resultados. Um resultado é um insumo de texto com um documento JSON. As tabelas de campos abaixo descrevem esse documento. Um campo marcado “só com” não aparece quando a conexão não tem o escopo; nunca chega como null.
Ids. Os ids são textos opacos. O mesmo id funciona na barra de endereços do console, na API /v1 e em outras ferramentas. Os nomes das pessoas não estão disponíveis pelo MCP: um campo como requesterId é um id.
Idioma. Na conexão OAuth, títulos, descrições, textos de erro e rótulos chegam no idioma solicitado. Os nomes de ferramentas e campos nunca mudam.
As perguntas de exemplo são o que um gestor poderia escrever para um assistente conectado ao muveya. O assistente decide qual ferramenta chamar.

`clinics.list`

List clinics and warehouses. Lista as unidades e os depósitos aos quais sua associação tem acesso, com o id, o nome e o status de cada um. Os assistentes a usam para descobrir os ids de que outras ferramentas precisam.


Escopo da conexão OAuth	`inventory:read` (interno `inventory.read`). `clinics:read` não é suficiente.
Argumentos	Nenhum
Omissão	Nada a omitir: só nomes, tipos e status

O resultado traz duas listas completas, em ordem de criação, incluindo unidades e depósitos inativos:

Campo	Significado
`clinics[].clinicId`	Id da unidade.
`clinics[].name`	Nome da unidade, por exemplo “Clínica Norte”.
`clinics[].status`	`active` ou `inactive`.
`warehouses[].warehouseId`	Id do depósito.
`warehouses[].name`	Nome do depósito.
`warehouses[].kind`	`central` ou `express`.
`warehouses[].clinicId`	A unidade à qual um depósito express pertence. Não aparece em um depósito central.
`warehouses[].status`	`active` ou `inactive`.

Perguntas de exemplo:

“Quais depósitos a Clínica Norte tem?”
“Liste as nossas unidades inativas.”

`catalog.search`

Search the catalog. Busca no catálogo por nome do insumo ou SKU e devolve os insumos correspondentes, com unidade, categoria e status. O custo só aparece quando a conexão pode vê-lo.


Escopo da conexão OAuth	`catalog:read` (interno `catalog.read`)
Campos de custo	Só com `catalog.cost:read` (interno `catalog.cost.read`)

string

Texto procurado no nome do insumo ou no SKU. Não diferencia maiúsculas de minúsculas e corresponde em qualquer parte do valor. De 1 a 120 caracteres. Sem ele, a ferramenta devolve os insumos do status escolhido.

string

padrão:"active"

Status do ciclo de vida a buscar: active, inactive ou draft.

O resultado é { items, truncated }. Traz no máximo 50 insumos, os mais antigos primeiro. Quando truncated é true, mais insumos corresponderam: pergunte de novo com um term mais específico.

Campo	Significado
`itemId`	Id do insumo.
`sku`	SKU, por exemplo `GLV-NIT-M`.
`name`	Nome do insumo.
`description`	Descrição, se o insumo tiver uma.
`categoryId`	Id da categoria do insumo (o nome da categoria não vem incluído).
`unitOfMeasure`	Unidade de medida em que o insumo é contado, por exemplo `box` ou `unit`. Veja os valores em `muveya://catalog/policies`.
`packaging`	Texto da embalagem, se definido.
`criticality`	`low`, `medium` ou `high`.
`tracksLot`, `tracksSerial`, `tracksExpiry`	Se as caixas deste insumo registram lote, número de série ou data de validade.
`highValue`	Se o insumo está marcado como de alto valor.
`status`	`draft`, `active` ou `inactive`. Só insumos `active` podem ser pedidos.
`costStatus`	Só com `catalog.cost:read`. `unset`, `verified`, `review_required` ou `invalid`.
`cost`, `currency`	Só com `catalog.cost:read`. O custo registrado em unidades menores de `currency` (por exemplo, centavos).
`costMeasurement`	Só com `catalog.cost:read`. A unidade e a versão de medida para as quais o custo foi registrado.

Só um custo verified corresponde à unidade de medida atual do insumo. Um custo em review_required ou invalid não é um preço que você possa usar. Veja Custos.

Perguntas de exemplo:

“Busque luvas de nitrilo no catálogo.”
“Quais insumos do catálogo ainda estão em rascunho?”
“Quanto custa uma caixa de GLV-NIT-M?” (só responde se a conexão tiver catalog.cost:read)

`inventory.check`

Check stock availability. Devolve quanto há de um insumo do catálogo em mãos, reservado e disponível em cada depósito, com opção de restringir a um só depósito.


Escopo da conexão OAuth	`inventory:read` (interno `inventory.read`)
Omissão	Só quantidades; nada a omitir

string

obrigatório

Id do insumo do catálogo, de 1 a 64 caracteres. Normalmente o assistente o encontra antes com catalog.search.

string

Id de um depósito, de 1 a 64 caracteres, para restringir a resposta a ele.

Campo	Significado
`catalogItemId`	O insumo consultado.
`warehouses[].warehouseId`	Um depósito que tem caixas do insumo. Ordenados por id.
`warehouses[].onHand`	Quantidade física nesse depósito, na unidade de medida do insumo.
`warehouses[].reserved`	Quantidade já reservada para pedidos.
`warehouses[].available`	`onHand` menos `reserved`.
`truncated`	`true` quando o insumo tem mais de 1000 caixas para somar: os números ficam parciais. Restrinja a consulta a um depósito.

Resultado de exemplo

{
  "catalogItemId": "6650aa00000000000000a001",
  "warehouses": [
    { "warehouseId": "6650bb00000000000000b001", "onHand": 40, "reserved": 12, "available": 28 },
    { "warehouseId": "6650bb00000000000000b002", "onHand": 6, "reserved": 0, "available": 6 }
  ],
  "truncated": false
}

Os números somam o saldo de todas as caixas do insumo em cada depósito. Eles não dizem quais caixas estão vencidas ou em quarentena; para o detalhe por caixa, use a página de cada caixa no console (veja Caixas e etiquetas). Um depósito sem caixas do insumo não aparece, e um insumo sem estoque (ou um id que não existe) devolve uma lista warehouses vazia, não um erro. Perguntas de exemplo:

“Quantas caixas de GLV-NIT-M estão disponíveis em cada depósito?”
“Ainda tem estoque desse insumo no Depósito Central?”

`orders.get`

Get an order. Devolve um pedido pelo id, com suas linhas, seu status e seu plano de aprovação.


Escopo da conexão OAuth	`orders:read` (interno `orders.read.all`)
Custo das linhas	Só com `catalog.cost:read`
Valor do pedido e `patientRef`	Nunca com OAuth

string

obrigatório

Id do pedido, de 1 a 64 caracteres. É o id opaco, não o número do pedido. No console, você pode copiá-lo do endereço da página do pedido, console.muveya.com/orders/ seguido do id.

Campo	Significado
`orderId`, `number`	Id e número legível do pedido.
`type`	`general` ou `clinical`.
`status`	Status atual, por exemplo `pending_approval` ou `dispatched`. Veja `muveya://orders/status-model`.
`requesterId`	Id do membro da equipe que criou o pedido.
`clinicId`	Unidade à qual o pedido pertence.
`destinationWarehouseId`	Depósito que recebe os insumos.
`preferredSourceWarehouseId`	Depósito preferido para o abastecimento, se definido.
`justification`	Justificativa informada por quem pediu, se houver.
`lines[]`	`lineId`, `catalogItemId`, `sku`, `name`, `requestedQty`, `unitOfMeasure`, `category` (o id da categoria quando a linha foi adicionada) e `highValue`.
`lines[].unitCost`, `lines[].currency`	Só com `catalog.cost:read`: o custo congelado na linha.
`approvalPlan`	Aparece quando o pedido já foi avaliado para aprovação: `policyVersion`, `requiresApproval` e `steps` (`stage`, `requiredScope`, `minApprovers`). O `evaluatedValue` e a `currency` dele nunca são mostrados a uma conexão OAuth.
`version`	Número da versão do registro do pedido.
`value`, `currency`	Total do pedido. Nunca é mostrado a uma conexão OAuth.
`patientRef`	Referência externa de paciente de um pedido clínico. Nunca é mostrada a uma conexão OAuth.

Se não existir pedido com esse id na sua clínica odontológica, ou se o id estiver malformado ou pertencer a outra clínica odontológica, o resultado é isError com code orders.not_found. O MCP não tem ferramenta para listar ou buscar pedidos; para listá-los, use GET /v1/orders ou a tela Pedidos do console (veja Criar e acompanhar pedidos). Perguntas de exemplo:

“Qual é o status do pedido 6650cc00000000000000c001 e de quais etapas de aprovação ele precisa?”
“Quais insumos e quantidades estão nesse pedido?”

`approvals.list_pending`

List pending approvals. Devolve os pedidos que aguardam a decisão de aprovação da própria pessoa conectada.


Permissão interna	`approvals.decide`
Com OAuth	Sempre recusada com `common.forbidden`
Argumentos	Nenhum

Esta ferramenta lê a caixa de aprovações de uma pessoa. A conexão atua como o membro da clínica odontológica que fez login, mas os escopos OAuth atuais de somente leitura não incluem approvals.decide. Por isso, a chamada é recusada antes de qualquer leitura. Para revisar e decidir aprovações hoje, use Aprovação de pedidos no console: veja Aprovar ou rejeitar pedidos. Para saber quantas aprovações estão pendentes, use management.briefing, cujos números incluem as aprovações pendentes por idade. Pergunta de exemplo: “O que está aguardando a minha aprovação?” (com OAuth, o assistente informará que a ferramenta não é permitida)

`management.pending_decisions`

Pending management decisions. A mesma caixa de aprovações de approvals.list_pending, apresentada para a gestão: cada pedido com o horário de envio (para medir a idade frente a um nível de serviço), suas etapas e o valor oculto, a menos que quem lê possa vê-lo.


Permissão interna	`approvals.decide`
Com OAuth	Sempre recusada com `common.forbidden`
Argumentos	Nenhum

Devolve exatamente o mesmo que approvals.list_pending e é recusada pelo mesmo motivo. Use Aprovação de pedidos no console, ou management.briefing para os números de aprovações pendentes. Pergunta de exemplo: “Quais decisões estão me aguardando há mais de dois dias?”

`fulfillment.get_pick_list`

Get a pick list. Devolve as caixas a separar para um pedido, com a validade mais próxima primeiro (FEFO), só caixas que continuam ativas.


Permissão interna	`fulfillment.pick`
Com OAuth	Sempre recusada com `common.forbidden`

string

obrigatório

Id do pedido a separar, de 1 a 64 caracteres.

A separação é feita por uma pessoa em um depósito, então esta ferramenta verifica a permissão de quem separa. Nenhum escopo OAuth concede fulfillment.pick (fulfillment:read também não). Para uma pessoa, cada linha traria lineId, catalogItemId, sku, boxId, boxCode, warehouseId, quantity, picked, requiresSeparation e, quando registrados, lotNumber e expiryDate; nunca custo, valor ou referência de paciente. Para separar pedidos hoje, use Entregas no console: veja Preparar e despachar um pedido. Pergunta de exemplo: “Quais caixas eu separo para este pedido?”

`analytics.consumption`

Consumption per supply. Devolve quanto foi consumido de cada insumo ao longo do tempo, cada um na sua própria unidade de medida, como um relatório com evidências. Nunca soma insumos ou unidades de medida diferentes.


Escopo da conexão OAuth	`analytics:read` (interno `reports.read`)
Omissão	Só quantidades; sem custo nem valor
Mesmo número que	O relatório de consumo do console e `GET /v1/analytics/consumption-trend`

string

Início da janela, em ISO-8601 (por exemplo 2026-08-01T00:00:00Z), incluído. De 1 a 40 caracteres. O padrão é 30 dias antes de to.

string

Fim da janela, em ISO-8601, excluído. De 1 a 40 caracteres. O padrão é agora.

string

padrão:"day"

Tamanho de cada intervalo: day ou week. Os intervalos seguem o horário UTC.

string

Id de um insumo do catálogo, de 1 a 64 caracteres, para restringir o relatório a ele.

from deve ser anterior a to, e a janela pode ter no máximo 366 dias. Uma data que não pode ser lida, uma janela invertida ou uma mais longa devolve isError com code common.invalid_request.

Campo	Significado
`metric`	`CONSUMPTION_TREND`.
`definition`	O que os números significam, em inglês.
`granularity`, `period.from`, `period.to`	Os intervalos e a janela realmente usados.
`timezone`, `asOf`, `freshness`	`UTC`, quando foi calculado e `live`.
`evidenceId`, `filters`	Uma descrição estável da consulta, para citar ou reproduzir o número.
`movementCount`	Movimentos de consumo lidos na janela.
`series[]`	Uma entrada por insumo e unidade de medida: `seriesKey`, `catalogItemId`, `itemName`, `sku`, `unitOfMeasure`, `totalConsumed`, `usedQuantity`, `issuedQuantity`, `movementCount` e `buckets`.
`series[].buckets[]`	`bucketStart`, `consumedQuantity`, `usedQuantity`, `issuedQuantity`, `movementCount`.
`unverifiedItems[]`	Insumos cujos movimentos não têm unidade verificada: são contados, nunca quantificados.
`coverage`	`measuredMovementCount`, `unverifiedMovementCount`, `warehouseScope` (limitado pelo acesso da pessoa aos depósitos) e, quando a leitura foi interrompida, `coveredFrom`.
`truncated`	`true` quando a leitura atingiu o limite; os números cobrem então só a partir de `coverage.coveredFrom`.
`narration`	Um conjunto de afirmações que um resumo pode fazer; só é incluído quando cada número confere com a tabela.

usedQuantity é o estoque registrado onde foi usado; issuedQuantity é o estoque entregue a salas que não contam seu estoque, um consumo estimado. Os dois somam a quantidade consumida. Análises gerenciais explica cada número. Perguntas de exemplo:

“Quantas unidades de cada insumo usamos por semana em agosto?”
“Mostre o consumo diário de GLV-NIT-M nos últimos 30 dias.”

`management.briefing`

Management briefing. Devolve o resumo gerencial reproduzível (um compêndio em que cada número se liga à sua métrica de origem e ao seu id de evidência) junto com a lista priorizada de exceções operacionais.


Escopo da conexão OAuth	`analytics:read` (interno `reports.read`)
Omissão	Só contagens, quantidades e durações; sem custo nem valor
Mesmos números que	`GET /v1/analytics/briefing` e `GET /v1/analytics/exceptions`

string

padrão:"daily"

daily ou weekly. Define se os números de consumo dentro do resumo são agrupados por dia ou por semana; os demais números não mudam.

O resultado é { briefing, exceptions }.

Campo	Significado
`briefing.metric`	`MANAGEMENT_BRIEFING`.
`briefing.period`, `briefing.definition`	O período pedido e o que o resumo contém.
`briefing.timezone`, `briefing.asOf`, `briefing.freshness`	`UTC`, quando foi calculado e `live`.
`briefing.evidenceId`	`MANAGEMENT_BRIEFING:period=daily` ou `MANAGEMENT_BRIEFING:period=weekly`.
`briefing.truncated`	`true` se algum número é um mínimo porque uma leitura atingiu o limite.
`briefing.figures[]`	`metric`, `dimension` (em uma métrica com várias linhas, como uma faixa de espera), `label` (em inglês neste endpoint), `value` (`null` quando não há amostra, nunca um zero inventado), `unit` e `evidenceId`.
`exceptions.total`	Quantidade de exceções encontradas.
`exceptions.exceptions[]`	`metric` (`EXPIRING_STOCK`, `DELIVERY_EXCEPTIONS`, `LOW_STOCK`, `RECEIPT_DISCREPANCIES` ou `PENDING_ORDERS`), `priority` (`0` é a mais urgente), `drillDownType` (`order`, `movement` ou `item`), `drillDownId`, `reference` (ids não sensíveis), `evidenceId` e, quando conhecido, `detectedAt`.
`exceptions.asOf`, `exceptions.evidenceId`, `exceptions.truncated`	Como no resumo.

O drillDownId de uma exceção é o id de um pedido, de um movimento de estoque ou de um insumo do catálogo. Um id order é aberto com orders.get; um id item, com inventory.check. Análises gerenciais define cada número. Perguntas de exemplo:

“Me dê o resumo de hoje e as três exceções mais urgentes.”
“O que mudou nesta semana? Use o resumo semanal.”

`management.compare_clinics`

Compare clinics. Ordena as suas unidades por volume de pedidos, com a definição da métrica à vista. Cada valor é uma contagem.


Escopo da conexão OAuth	`analytics:read` (interno `reports.read`)
Argumentos	Nenhum
Omissão	Só contagens; nunca inclui o valor dos pedidos
Mesmo número que	`GET /v1/analytics/clinics/comparison`

Campo	Significado
`metric`, `definition`, `unit`	`ORDERS_BY_CLINIC`, a definição em inglês e `orders`.
`timezone`, `asOf`, `freshness`, `evidenceId`, `filters`	Como nos demais relatórios.
`truncated`	`true` quando a contagem de pedidos atingiu o limite: as contagens são então um mínimo.
`clinics[]`	`clinicId`, `clinicName`, `clinicStatus`, `totalOrders` e `pendingApprovalOrders`.

Todas as unidades aparecem, inclusive as que não têm pedidos. A lista é ordenada por totalOrders, do maior para o menor; os empates são ordenados por clinicId. Perguntas de exemplo:

“Qual unidade fez mais pedidos?”
“Compare as nossas unidades por aprovações pendentes.”

Páginas relacionadas

Servidor MCP

Escopos, omissão de dados, auditoria e erros.

Conectar um cliente

Configure o Claude Code, o Claude Desktop, o Cursor ou o seu próprio cliente.

Recursos MCP

Documentos de referência que ajudam um assistente a ler estes resultados.

Análises gerenciais

A definição de cada número gerencial.

​Como ler esta página

​clinics.list

​catalog.search

​inventory.check

​orders.get

​approvals.list_pending

​management.pending_decisions

​fulfillment.get_pick_list

​analytics.consumption

​management.briefing

​management.compare_clinics

​Páginas relacionadas

Servidor MCP

Conectar um cliente

Recursos MCP

Análises gerenciais

Como ler esta página

`clinics.list`

`catalog.search`

`inventory.check`

`orders.get`

`approvals.list_pending`

`management.pending_decisions`

`fulfillment.get_pick_list`

`analytics.consumption`

`management.briefing`

`management.compare_clinics`

Páginas relacionadas