Recursos MCP - muveya

Além das ferramentas, o servidor MCP do muveya oferece quatro recursos: documentos JSON que um assistente pode ler para entender os seus dados antes de responder. Um cliente os lista com resources/list e lê um deles com resources/read e a sua URI. Cada leitura devolve um item cujo mimeType é application/json e cujo text é o documento JSON.

URI	Nome	Título	Quem pode ler com OAuth
`muveya://help/error-codes`	`error-codes`	Error code catalog	Qualquer conexão OAuth ativa
`muveya://orders/status-model`	`orders-status-model`	Order status model	Qualquer conexão OAuth ativa
`muveya://catalog/policies`	`catalog-policies`	Catalog policies	Qualquer conexão OAuth ativa
`muveya://tenant/approval-policy-summary`	`approval-policy-summary`	Approval policy summary	Nunca: precisa de `approvals.decide`

Com OAuth, os títulos e as descrições seguem o idioma solicitado. Os três primeiros são documentos de referência. Eles não contêm dados da sua clínica odontológica: todas as conexões recebem exatamente o mesmo conteúdo, então não precisam de escopo. O quarto é montado a partir da política de aprovação da sua clínica odontológica e é restrito às pessoas que decidem aprovações. Cada leitura, permitida ou recusada, fica registrada no histórico de auditoria como mcp.resource_read, com a URI, quem chamou e o resultado. Veja a seção Auditoria em Servidor MCP.

`muveya://help/error-codes`

Error code catalog. Todos os códigos de erro estáveis que o muveya pode devolver, com o status HTTP e a URI que os nomeia. Um assistente o usa para explicar um erro e decidir o que fazer com base no code, nunca no texto para pessoas.


Restrição	Nenhuma: qualquer conexão OAuth ativa
Omissão	Nada a omitir: o documento não tem dados da sua clínica odontológica

O documento é { errors }, ordenado por code. Cada entrada tem:

Campo	Significado
`code`	O código estável, por exemplo `orders.not_found`.
`status`	O status HTTP correspondente, por exemplo `404`.
`type`	A URI do campo `type` de um documento de problema: `https://docs.muveya.com/errors/` seguido do código.

Trecho

{
  "errors": [
    { "code": "api_keys.invalid", "status": 401, "type": "https://docs.muveya.com/errors/api_keys.invalid" },
    { "code": "common.forbidden", "status": 403, "type": "https://docs.muveya.com/errors/common.forbidden" },
    { "code": "orders.not_found", "status": 404, "type": "https://docs.muveya.com/errors/orders.not_found" }
  ]
}

O catálogo cobre todos os códigos do produto, inclusive os que só o console ou a API /v1 podem devolver. Para saber o que cada código significa e como resolver, veja Erros e Solução de problemas.

`muveya://orders/status-model`

Order status model. O ciclo de vida do pedido: cada status e cada transição permitida entre eles. Um assistente o usa para explicar em que ponto um pedido está e qual evento pode levá-lo adiante.


Restrição	Nenhuma: qualquer conexão OAuth ativa
Omissão	Nada a omitir: o documento não tem dados da sua clínica odontológica

O documento é { statuses, transitions }. statuses lista os 14 status. Cada entrada de transitions tem um event, os status from de onde ele pode partir e o único status to a que ele leva. Qualquer mudança que não esteja na lista é recusada. O documento traz só os valores. Os significados abaixo são desta página:

Status	Significado
`draft`	Em preparação; ainda não enviado.
`submitted`	Enviado; a política de aprovação está sendo aplicada.
`pending_approval`	Aguardando decisões de aprovação.
`approved`	Aprovado, por pessoas ou automaticamente quando nenhuma aprovação era exigida.
`rejected`	Rejeitado. Final.
`cancelled`	Cancelado antes de uma decisão. Final.
`allocated`	Estoque reservado para o pedido.
`picking`	A separação começou.
`dispatched`	As caixas saíram do depósito de origem.
`delivered`	Entrega confirmada sem exceção.
`exception`	Entrega confirmada com uma exceção.
`received`	Recebido no destino sem problemas.
`partially_fulfilled`	Recebido com uma contestação (danificado, faltante ou parcial).
`closed`	Encerrado pelo destino quando todas as linhas foram resolvidas. Final.

`event`	`from`	`to`
`submit`	`draft`	`submitted`
`cancel`	`draft`, `submitted`, `pending_approval`	`cancelled`
`attach_plan`	`submitted`	`pending_approval`
`auto_approve`	`submitted`	`approved`
`approve`	`pending_approval`	`approved`
`reject`	`pending_approval`	`rejected`
`allocate`	`approved`	`allocated`
`pick`	`allocated`	`picking`
`dispatch`	`picking`	`dispatched`
`deliver`	`dispatched`	`delivered`
`fail_delivery`	`dispatched`	`exception`
`receive`	`delivered`	`received`
`partially_receive`	`delivered`	`partially_fulfilled`
`close`	`received`, `partially_fulfilled`	`closed`

Um pedido em exception não pode ser encerrado. Para os detalhes de cada etapa, veja Criar e acompanhar pedidos e Entregas: visão geral.

`muveya://catalog/policies`

Catalog policies. O vocabulário e as regras do catálogo: unidades de medida, criticidade, status de insumo, indicadores de rastreabilidade e como o custo é ocultado sem permissão. Um assistente o usa para ler corretamente os resultados de catalog.search.


Restrição	Nenhuma: qualquer conexão OAuth ativa
Omissão	Nada a omitir: descreve a regra do custo, mas não contém custos

O documento é igual para todos:

{
  "units": ["unit", "box", "pack", "bottle", "ampoule", "milliliter", "liter", "gram", "kilogram", "pair", "kit"],
  "criticalities": ["low", "medium", "high"],
  "statuses": ["draft", "active", "inactive"],
  "settableStatuses": ["active", "inactive"],
  "orderableStatus": "active",
  "flags": [
    { "field": "tracksLot", "default": false },
    { "field": "tracksSerial", "default": false },
    { "field": "tracksExpiry", "default": false },
    { "field": "highValue", "default": false }
  ],
  "costRedaction": { "scope": "catalog.cost.read", "behavior": "absent-when-unauthorized" }
}

Campo	Significado
`units`	As unidades de medida em que um insumo pode ser contado (`unitOfMeasure`).
`criticalities`	Os níveis de criticidade de um insumo.
`statuses`	Status de um insumo. Um insumo nasce em `draft`.
`settableStatuses`	Os status para os quais um insumo pode passar: `active` ou `inactive`. Um insumo nunca volta para `draft`.
`orderableStatus`	Só insumos `active` podem ser pedidos.
`flags`	As configurações de sim ou não de um insumo e o seu valor padrão. `tracksLot`, `tracksSerial` e `tracksExpiry` definem o que uma caixa registra e como as caixas são escolhidas na separação; `highValue` alimenta a política de aprovação e uma custódia mais rigorosa.
`costRedaction`	Os campos de custo são omitidos por completo, a menos que quem lê tenha `catalog.cost.read` (o escopo OAuth `catalog.cost:read`).

Veja Insumos do catálogo e Custos para as regras por trás de cada valor.

`muveya://tenant/approval-policy-summary`

Approval policy summary. Um resumo versionado da política de aprovação vigente da sua clínica odontológica: regras, etapas e permissões exigidas, com os limites monetários só para quem pode ver o valor dos pedidos.


Restrição	Permissão interna `approvals.decide`. Nenhum escopo OAuth a concede.
Com OAuth	Sempre recusado; nada é lido
Omissão	`minValue` e `maxValue` são omitidos, a menos que quem lê possa ver o valor dos pedidos

Como tem restrição, uma conexão OAuth atual recebe um erro JSON-RPC em vez do documento:

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32600,
    "message": "MCP error -32600: Not authorized to read this resource",
    "data": { "code": "common.forbidden" }
  }
}

Mesmo assim, ele aparece em resources/list. Para uma pessoa com permissão para lê-lo, algo que ainda não está disponível, o documento é { "configured": false, "rules": [] } quando nenhuma política foi publicada, ou configured: true com:

Campo	Significado
`policyVersion`, `isCurrent`, `effectiveFrom`, `publishedBy`	Qual versão está vigente, desde quando e o id de quem a publicou.
`rules[].when`	As condições de uma regra: `categories`, `highValue`, `orderTypes` e os limites `minValue` e `maxValue` quando quem lê pode vê-los. Uma condição ausente vale para tudo.
`rules[].require`	O que a regra exige: a etapa (`stage`), a permissão (`requiredScope`) que quem aprova deve ter e `minApprovers`.

Para ver ou alterar a política de aprovação hoje, use o console: veja Política de aprovação.

Erros ao ler um recurso

Uma leitura de recurso que falha devolve um erro JSON-RPC, não um resultado com isError:

Situação	`error.code`	`error.message`	`error.data.code`
A conexão não tem a permissão do recurso	`-32600`	`MCP error -32600: Not authorized to read this resource`	`common.forbidden`
Uma regra do muveya recusou a leitura	`-32600`	`MCP error -32600: The resource could not be read`	O código estável, por exemplo `common.forbidden`
Algo falhou do lado do muveya	`-32603`	`MCP error -32603: The resource could not be read`	`common.internal_error`
A URI não é nenhuma das quatro acima	`-32602`	`MCP error -32602: Resource` seguido da URI e de `not found`	Não aparece

Páginas relacionadas

Servidor MCP

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

Ferramentas MCP

As dez ferramentas de leitura e o que elas devolvem.

Conectar um cliente

Configure o seu assistente e teste o endpoint.

Erros

O que cada código de erro significa.

​muveya://help/error-codes

​muveya://orders/status-model

​muveya://catalog/policies

​muveya://tenant/approval-policy-summary

​Erros ao ler um recurso

​Páginas relacionadas