Skip to content

MCP usage guide: what each person can do

The usage guide is a manual computed for whoever asks. It tells the person what they can ask OrpycaMCP to do with today's permissions, ordered by workflow, with one example phrase per action. It also gives an MCP client what it needs to execute each action. The client can be the in-app assistant, Hermes, Claude or any other.

Example phrases are in Spanish: they are what a Spanish-speaking user would say.

How to request it

Channel For Returns
Resource orfeo://guia the MCP client JSON: workflows, actions, tool, parameters and confirmation
Prompt guia_de_uso the person the same content as text, plus the instruction not to attempt what is denied

Both outputs come from the same function, so what the person reads and what the client acts on cannot disagree.

What it contains

  • Chapters by workflow, in the order of the procedure (registry desk, routing, reply and dispatch, case file, physical archive, transfers, disposal, preservation and signature, archival instruments, mail, search, administration, notifications). A workflow with nothing allowed and nothing denied is left out.
  • What the person can do: actions, guided procedures (several steps, one confirmation) and queries, each with its example phrase.
  • What the person cannot do, with the reason and the alternative route. The reason tells apart a missing permission from a read-only level.
  • What this channel does not offer by decision, in its own chapter, with reason and where it is done instead.
  • Clarifications the system does not distinguish and the assistant must not claim.

How a client uses it to execute

Each action carries herramienta (the tool to call), parametros with obligatorio (required) and, for writes, confirmacion. A write never runs on the first call: the server returns a signed proposal the person approves with confirmar_accion; an act with minutes is approved in their session, at /aprobar. If the request matches an entry in no_puede, the client answers with the reason and the alternative route without trying.

The server re-checks permissions on every call. The guide orients; it does not authorize.

For a model with little context

The full guide does not fit in a model's context, so there are short pieces: orfeo://indice gives the map, guia_flujo one page per workflow, buscar_herramientas and describir_herramienta the action and its parameters, and explicar_limite the reason for a no. To connect a client, see Connect an MCP client.

Task guides (how it is done)

Besides the per-workflow guide there are task guides (ADR-072 D2): "register an incoming document", "transfer a radicado", "close and archive an expediente"... Each one carries the steps, the screen for each step and the fields that are asked for (with their label and whether they are required, taken from the tool itself). They are read with the guia_de_tarea tool (without arguments it lists the tasks), with the resource orfeo://guia/{tarea} or over REST at GET /api/v1/mcp/guias[/{tarea}]. What the person cannot do comes out separately, without steps, with whom to ask. They do not use the model nor depend on the assistant flag.

When data is missing (preparar_tramite)

Before proposing a write with incomplete data, the client calls the preparar_tramite(tarea, datos) tool (tarea is a guide key or a tool name; datos, what is already known). It is a server read: it saves nothing, writes nothing and dispatches nothing. It returns listo, resueltos, faltan —each with campo, etiqueta, pregunta (how to ask the person) and opciones_desde (the catalogue read the valid values come from: listar_dependencias, listar_tipos_documentales...)—, invalidos and, if ready, ejecutaria with the tool, the arguments and the confirmation rung. It covers conditionally required fields (fecha_documento on an Entrada) and "exactly one of" groups. Rule: ask for what is missing, one question at a time when there are several references, and UUIDs and codes are never invented or inferred: they come from the read. Preparing is not approving: executing still goes through the proposal and its confirmation.

Today's pending items (mis_pendientes)

The mis_pendientes tool (no arguments) and GET /api/v1/mcp/hoy return, for each routine the person's profile reaches, {clave, titulo, conteo, enlace, guia}: how many radicados to process, signatures to give, drafts in progress, annulments to decide, overdue loans... Routines come from the permission and level (not from the role name): the one the person does not reach does not appear. Each count is computed by the domain service with the person's token (clearance and privacy included); if a read fails or is slow, the count is null and no reason is given. It carries no document content, only counts and the link to the screen where it is handled. It also answers with the assistant turned off.

Reports (preparar_informe)

The preparar_informe(informe, dimension, desde, hasta) tool and GET /api/v1/mcp/informes (catalogue, without the assistant flag) cover the first cut of reports: counts only for the person's active dependencia by status, type and month (radicados, overdue and soon-to-be-overdue procedures), without people's names. Only the summary reaches the model (total, number of groups and the count per value if there are few) and the normalized descriptor; the rows are requested by the person's browser with their session. The catalogue is closed: a key, dimension or filter outside it gives 422, and the model never builds the route. Clearance and privacy are applied in the WHERE of the count, so the person only counts what they can already read; each query leaves the report.consultado audit entry.

Bulk processing actions (*_en_masa)

First cut (ADR-072 D6): assign, transfer and inform several radicados, up to 20 over this channel (the application allows 100). Always in two steps: first vista_previa_asignar_en_masa (or _trasladar_, _informar_), a read that writes nothing and says, per radicado, whether it proceeds (aplicable), why not (rechazado and its codigo_error) or no_encontrado (non-existent or not visible to the person: the same result, with no cause), and returns a huella (fingerprint). Then asignar_en_masa (or trasladar_en_masa, informar_en_masa) with the same radicados and parameters, the huella and a new clave_idempotencia (a UUID): it returns the rung-3 proposal and the card lists the radicados; it is confirmed by typing how many there are. If the selection changed between the preview and the confirmation, the server answers 409 seleccion_cambiada and executes nothing. Each radicado is its own act with its audit entry; an item that fails does not undo the others, and the result is per item (consultar_operacion_masiva). Repeating the same key returns the same batch.

Second cut (increment 7): include several radicados in an expediente, with the same contract. vista_previa_incluir_radicados_en_expediente_en_masa (read, writes nothing, returns the huella), then incluir_radicados_en_expediente_en_masa with the expediente_id, the same radicados, the motivo, the huella and a new clave_idempotencia: rung 3 (confirmed by typing how many there are), up to 20, gate USUA_PERM_EXPEDIENTE level 2 (that of the individual link). Each radicado is its own link with its audit entry: an annulled one, an untyped one or one already linked is left rechazado with its codigo_error without undoing the others, and a non-existent one or one the person cannot see is no_encontrado. The expediente must be readable (otherwise it is the same 404 as a non-existent one). consultar_inclusion_masiva_en_expediente gives the batch result. vincular_radicados_en_lote (all-or-nothing, up to 500) still exists.

Over this channel the following are not offered in bulk: annul, inactivate, reclassify, declassify, change privacy, sign or give approval (visto bueno), approve drafts, retype, legal retention, return, finalize or archive (NO_OFRECIDAS), nor reprocessing the failed items of a batch: for those, one by one or from the application.

Where it comes from

It is not written by hand. Every read composes it from the scope framework (mi_alcance), the MCP server's workflow map (the same one the API by workflow census uses) and the example phrase each tool declares. For queries the phrase is derived from the operation. A new tool shows up in the guide without touching the guide. A guardian requires every write and every procedure to declare its phrase.