Connect an MCP client¶

An external assistant (Hermes, Claude or another MCP client) connects to OrpycaMCP with an assistant credential: a URL and a header, with no bridge and no stored password. It acts as the person who issued the credential, with their permissions, trimmed by the ceiling they choose. Every act is audited under their name, with canal=mcp and the credential identifier.

The design is in ADR-067 (Spanish).

Before you start¶

The institution must allow it. An administrator (USUA_PERM_ADMIN level 3) turns on «Permitir asistentes externos» under Administración → Parámetros. It ships off. Turning it off cuts every live credential within about 15 seconds.
Each person issues their own under Mi perfil → Conectar un asistente, from their browser session. A credential cannot issue another one.

Issue the credential¶

Field	Default	Meaning
Name	required	To recognize it, for example «Hermes on the laptop»
Validity	90 days	Up to 365. The screen warns at 14 days or fewer
Maximum security level (`techo_nivel`)	1	Up to which classification level the assistant can see. Raise it only if the model is local: what the assistant sees reaches the model
Scope of acts (`techo_crud`)	3	1 read only; 2 also modifies what exists; 3 also creates and withdraws
Allow upload (`permite_subida`)	no	Lets the same credential upload files
Allowed networks (`cidr_permitidos`)	none	Limits where it can be used from

You need an active second factor in your profile, and you are asked for the code; without it, 403 totp_requerido. The secret is shown only once; if you lose it, revoke it and issue another. You can hold up to 5 live ones. The ceiling never grants more than you have: it only trims.

Treat the credential like a password: keep it in a secret manager or the client's environment file, never in a repository or a message. It only works on MCP and upload; the rest of the API answers 401.

Configure the client¶

Use POST /api/v1/mcp/compacto, designed for a model: few tools, an index and a search tool. Everything within your reach stays available. Declare the URL and the header; with Hermes:

mcp_servers:
  orpyca:
    url: https://<your-institution-api>/api/v1/mcp/compacto
    headers:
      Authorization: Bearer ${ORPYCA_CREDENCIAL}
    timeout: 120
    connect_timeout: 30

The credential carries the institution inside: X-Tenant-Slug is not needed.

Entry point	Purpose
`/api/v1/mcp/compacto`	A model with limited context. `buscar_herramientas`, `describir_herramienta`, `invocar_herramienta` and a frequently used core
`/api/v1/mcp/stream`	A client that wants the whole catalog at once
`/api/v1/mcp/sesion`	A session client that supports elicitation. The session is bound to your credential and closes after 30 idle minutes

How the model works¶

On connecting it receives the server instructions. The orfeo://indice resource shows the workflows and what is within reach.
guia_flujo details a workflow. buscar_herramientas finds the action and describir_herramienta gives its parameters, including obligatorios_condicionales.
A write never runs on the first call: it returns a prop:<id> proposal that lives 10 minutes and is consumed once. The person reviews it with consultar_propuesta and confirms with confirmar_accion.
When something cannot be done, explicar_limite gives the reason and the alternative route, without trying.

The four confirmation levels¶

Level	What it asks	Examples
1	Nothing: read only	Consulting, searching
2	Confirm the proposal, with its phrase if any	Registering, transferring
3	Type a value the model cannot guess	Setting a legal hold, reactivating, deciding an expiry
4	Approve in the person's session	Acts with minutes: batches, TRD and TVD, PINAR, approvals

At level 4, confirmar_accion answers 403 sesion_requerida with a url_aprobacion (https://<app>/aprobar#prop:<id>). The person opens it, logs in if needed, reviews the card and approves. The link lives 15 minutes and only works for whoever prepared the act. The audit entry records confirmado_en=sesion.

Five "I have read it and I approve" acts show the document. firmar_anexo_simple, dar_visto_bueno, dar_vobo_cadena_firma, aprobar_version_publica and elaborar_version_publica are not approved looking only at a registration number: /aprobar shows the PDF (for the simple signature, also the attachment's name, size and SHA-256 digest; for the sign-off, the subject; for a signature-chain sign-off, the draft's text or the registration's PDF with the digest the chain anchored; for the public version, the redacted PDF and the original to compare them and, when approving it, what was redacted and why) and does not allow approving if it cannot show it (no permission, unavailable, not a PDF) or if it changed. For you, who connect the client:

When the act is prepared, the server binds the document's file_id and digest to the signed proposal; neither the model nor you set them. With no readable document, or not a PDF, there is no proposal (visor_no_disponible).
If the file changes before approval the act does not run: 409 archivo_cambiado. The proposal is no longer valid; prepare the act again so the person sees the current document.
confirmar_accion (and the web assistant) NEVER complete a level-4 act, even with an interactive session: they answer 403 sesion_requerida with url_aprobacion. With this credential proposals always arrive as prop:….
The bytes are requested by the person's browser with their session, through the radicado's normal routes. What the model receives does not change: no file_id or digest appears in the proposal or in consultar_propuesta.

This channel offers nothing that widens one's own scope (groups, permissions, clearance, credentials), nor the rule by which deadlines are counted and work is distributed (calendar, parameters, time zone, closed catalogues, departments, assignment rules). Document templates and the metadata schema are offered: the schema requires the last signature in the person's session (step 4).

Channels with no person present (incoming mail, scheduled tasks): exclude confirmar_accion and do not use upload. The server cannot know who typed a phrase: the control belongs to the client.

Read the result¶

Every tool returns the same result, and an error is flagged with isError:

`efecto`	Meaning	What to do
`si`	It happened	Continue
`no`	It did not happen	Read `error` and `que_hacer`
`parcial`	Part of it happened	Read `campos` and `que_hacer`
`desconocido`	Unknown, due to a failure after the proposal was consumed	Do not retry: check first

Upload a file¶

Bytes do not go through the model. A client component uploads them with the same header and hands the model the identifier:

curl -X POST "https://<your-institution-api>/api/v1/storage/upload" \
  -H "Authorization: Bearer $ORPYCA_CREDENCIAL" -F "file=@letter.pdf"

It requires permite_subida and the person's permission to upload. With techo_crud 1 and upload on, bytes can be uploaded, but linking them to a document needs a write that ceiling does not allow.

Connection errors¶

Response	Cause	What to do
`401 credencial_asistente_fuera_de_alcance`	Used on a route that is neither MCP nor upload	Fix the URL
`401 credencial_asistente_fuera_de_red`	The source network is not in `cidr_permitidos`	Review the networks or issue another
`401 invalid_token`	Credential expired, revoked or miscopied, account deactivated, or the institution has the switch off	Check Mi perfil; if still valid, ask the administrator
`403 permiso_insuficiente`	The request exceeds the permission or the ceiling; `motivo` says which	Issue another with a higher ceiling, or do it on screen
`403 sesion_requerida`	Level 4 act	Open `url_aprobacion`
`409 propuesta_consumida` / `410 propuesta_expirada`	Already used or expired	Prepare the act again

Revoke¶

Each person revokes their own under Mi perfil. An administrator does so under Administración → Usuarios (read at level 1; revoke at level 3 with a reason). Revocation takes up to 15 seconds. Nothing is deleted: the credential is marked with who and why.

If a person leaves the institution, deactivate their account under Administración → Usuarios ("Dar de baja", with a reason). Deactivation cuts the open session and every later request within a minute, and revokes their assistant credentials, which do not come back when the account is reactivated (new ones are issued). Nothing is deleted. Disabling the account in the identity provider alone cuts nothing: the cut lives in the institution's token validation.

For whoever deploys¶

New variables: ASISTENTE_PEPPER in auth-service (required; changing it invalidates every credential) and REDIS_URL and APP_BASE_URL in mcp-server. The gateway and the services with signed identity are updated in the same deployment. Details in Deployment.