> ## Documentation Index
> Fetch the complete documentation index at: https://muveya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ferramentas MCP

> Cada ferramenta do servidor MCP do muveya: o que devolve, seus argumentos, o escopo de que precisa, o que oculta e uma pergunta que um gestor poderia fazer.

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`) |

<ParamField body="term" type="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.
</ParamField>

<ParamField body="status" type="string" default="active">
  Status do ciclo de vida a buscar: `active`, `inactive` ou `draft`.
</ParamField>

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`](/docs/pt/mcp/resources). |
| `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. |

<Warning>
  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](/docs/pt/catalog/costs).
</Warning>

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 |

<ParamField body="catalogItemId" type="string" required>
  Id do insumo do catálogo, de 1 a 64 caracteres. Normalmente o assistente o encontra antes com `catalog.search`.
</ParamField>

<ParamField body="warehouseId" type="string">
  Id de um depósito, de 1 a 64 caracteres, para restringir a resposta a ele.
</ParamField>

| 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. |

```json Resultado de exemplo theme={null}
{
  "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](/docs/pt/inventory/boxes)). 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 |

<ParamField body="orderId" type="string" required>
  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.
</ParamField>

| 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`](/docs/pt/mcp/resources). |
| `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](/docs/pt/orders/create-and-track)).

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](/docs/pt/orders/approvals). 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` |

<ParamField body="orderId" type="string" required>
  Id do pedido a separar, de 1 a 64 caracteres.
</ParamField>

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](/docs/pt/deliveries/picking).

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](/docs/pt/reports/consumption) do console e `GET /v1/analytics/consumption-trend` |

<ParamField body="from" type="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`.
</ParamField>

<ParamField body="to" type="string">
  Fim da janela, em ISO-8601, excluído. De 1 a 40 caracteres. O padrão é agora.
</ParamField>

<ParamField body="granularity" type="string" default="day">
  Tamanho de cada intervalo: `day` ou `week`. Os intervalos seguem o horário UTC.
</ParamField>

<ParamField body="catalogItemId" type="string">
  Id de um insumo do catálogo, de 1 a 64 caracteres, para restringir o relatório a ele.
</ParamField>

`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](/docs/pt/reports/management-analytics) 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` |

<ParamField body="period" type="string" default="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.
</ParamField>

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](/docs/pt/reports/management-analytics) 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

<CardGroup cols={2}>
  <Card title="Servidor MCP" icon="plug" href="/docs/pt/mcp/introduction">
    Escopos, omissão de dados, auditoria e erros.
  </Card>

  <Card title="Conectar um cliente" icon="link" href="/docs/pt/mcp/connect">
    Configure o Claude Code, o Claude Desktop, o Cursor ou o seu próprio cliente.
  </Card>

  <Card title="Recursos MCP" icon="book" href="/docs/pt/mcp/resources">
    Documentos de referência que ajudam um assistente a ler estes resultados.
  </Card>

  <Card title="Análises gerenciais" icon="chart-line" href="/docs/pt/reports/management-analytics">
    A definição de cada número gerencial.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.