Conectar un cliente MCP¶

Un asistente externo (Hermes, Claude u otro cliente MCP) se conecta a OrpycaMCP con una credencial de asistente: una URL y una cabecera, sin puente ni contraseña guardada. Actúa como la persona que emitió la credencial, con sus permisos, recortados por el techo que ella elija. Cada acto queda en la auditoría a su nombre, con canal=mcp y el identificador de la credencial.

El diseño está en ADR-067.

Antes de empezar¶

La entidad debe permitirlo. Un administrador (USUA_PERM_ADMIN nivel 3) enciende «Permitir asistentes externos» en Administración → Parámetros. Viene apagado. Apagarlo deja sin servicio toda credencial viva en unos 15 segundos.
Cada persona emite la suya en Mi perfil → Conectar un asistente, desde su sesión en el navegador. Una credencial no puede emitir otra.

Emitir la credencial¶

Campo	Por defecto	Qué significa
Nombre	obligatorio	Para reconocerla, por ejemplo «Hermes del portátil»
Vigencia	90 días	Máximo 365. La pantalla avisa cuando faltan 14 días o menos
Nivel de seguridad máximo (`techo_nivel`)	1	Hasta qué nivel de clasificación puede ver el asistente. Súbalo solo si el modelo es local: lo que ve el asistente llega al modelo
Alcance de los actos (`techo_crud`)	3	1 solo consulta; 2 además modifica lo existente; 3 además crea y retira
Permitir subida (`permite_subida`)	no	Deja subir archivos con la misma credencial
Redes permitidas (`cidr_permitidos`)	ninguna	Limita desde qué redes se puede usar

Necesita el segundo factor activo en su perfil, y se le pide el código; sin él, 403 totp_requerido. El secreto se muestra una sola vez; si lo pierde, revóquela y emita otra. Puede tener hasta 5 vivas. El techo nunca da más de lo que usted tiene: solo recorta.

Trate la credencial como una contraseña: guárdela en el gestor de secretos o en el archivo de entorno del cliente, nunca en el repositorio ni en un mensaje. Solo sirve en el MCP y en la subida; contra el resto del API responde 401.

Configurar el cliente¶

Use POST /api/v1/mcp/compacto, pensado para un modelo: pocas herramientas, un índice y un buscador. Todo lo que usted alcanza sigue disponible. Declare la URL y la cabecera; con Hermes:

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

La credencial lleva la entidad dentro: no hace falta X-Tenant-Slug.

Punto de entrada	Para qué
`/api/v1/mcp/compacto`	Un modelo con contexto limitado. `buscar_herramientas`, `describir_herramienta`, `invocar_herramienta` y un núcleo de uso frecuente
`/api/v1/mcp/stream`	Un cliente que quiere todo el catálogo de una vez
`/api/v1/mcp/sesion`	Un cliente con sesión que admite elicitación. La sesión queda atada a su credencial y se cierra tras 30 minutos sin uso

Cómo trabaja el modelo¶

Al conectarse recibe las instructions del servidor. Con el recurso orfeo://indice ve los flujos y lo que tiene a su alcance.
guia_flujo trae el detalle de un flujo. buscar_herramientas encuentra la acción y describir_herramienta da sus parámetros, incluidos obligatorios_condicionales.
Una escritura nunca se ejecuta en la primera llamada: devuelve una propuesta prop:<id> que vive 10 minutos y se consume una sola vez. La persona la revisa con consultar_propuesta y la confirma con confirmar_accion.
Si algo no se puede, explicar_limite da el motivo y la vía alternativa, sin intentarlo.

Los cuatro niveles de confirmación¶

Peldaño	Qué pide	Ejemplos
1	Nada: solo lee	Consultar, buscar
2	Confirmar la propuesta, con su frase si la tiene	Radicar, trasladar
3	Teclear un dato que el modelo no puede adivinar	Fijar retención legal, reactivar, decidir un vencimiento
4	Aprobar en la sesión de la persona	Actos con acta: lotes, TRD y TVD, PINAR, visto bueno

En el peldaño 4, confirmar_accion responde 403 sesion_requerida con un url_aprobacion (https://<app>/aprobar#prop:<id>). La persona lo abre, inicia sesión si hace falta, revisa la tarjeta y aprueba. El enlace vive 15 minutos y solo sirve a quien preparó el acto. El asiento registra confirmado_en=sesion.

Cinco actos de «lo he leído y lo apruebo» muestran el documento. firmar_anexo_simple, dar_visto_bueno, dar_vobo_cadena_firma, aprobar_version_publica y elaborar_version_publica no se aprueban viendo solo el número de radicado: /aprobar muestra el PDF (en la firma simple, también el nombre, el tamaño y la huella SHA-256 del anexo; en el visto bueno, el asunto; en el visto bueno de una cadena de firma, el texto del borrador o el PDF del radicado con la huella que la cadena ancló; en la versión pública, el PDF tachado y el original para compararlos y, al aprobarla, qué se tachó y por qué) y no deja aprobar si no puede mostrarlo (sin permiso, no disponible, no es PDF) o si cambió. Para usted, que conecta el cliente:

Al preparar el acto, el servidor ata file_id y huella del documento a la propuesta firmada; ni el modelo ni usted los ponen. Si no hay documento legible, o no es un PDF, no hay propuesta (visor_no_disponible).
Si el archivo cambia antes de aprobar, el acto no se ejecuta: 409 archivo_cambiado. La propuesta no sirve más; prepare el acto de nuevo para que la persona vea el documento actual.
confirmar_accion (y el asistente web) NUNCA completan un peldaño 4, ni con sesión interactiva: responden 403 sesion_requerida con url_aprobacion. Con esta credencial las propuestas llegan siempre como prop:….
Los bytes los pide el navegador de la persona con su sesión, por las rutas normales del radicado. Lo que recibe el modelo no cambia: ni file_id ni huella salen en la propuesta ni en consultar_propuesta.

Por este canal no se ofrece nada que ensanche el propio alcance (grupos, permisos, clearance, credenciales), ni la regla con que se cuentan los plazos y se reparte el trabajo (calendario, parámetros, zona horaria, catálogos cerrados, dependencias, reglas de reparto). Las plantillas de documento y el esquema de metadatos sí: el esquema exige la última firma en la sesión de la persona (peldaño 4).

Canales sin una persona presente (correo entrante, tareas programadas): excluya confirmar_accion y no use subida. El servidor no puede saber quién tecleó una frase: el control es del cliente.

Leer el resultado¶

Toda herramienta devuelve el mismo resultado, y el error viene marcado con isError:

`efecto`	Qué significa	Qué hacer
`si`	Ocurrió	Seguir
`no`	No ocurrió	Leer `error` y `que_hacer`
`parcial`	Ocurrió una parte	Leer `campos` y `que_hacer`
`desconocido`	No se sabe, por un fallo tras consumir la propuesta	No reintentar: consultar primero

Subir un archivo¶

Los bytes no pasan por el modelo. Un componente del cliente los sube con la misma cabecera y le pasa al modelo el identificador:

curl -X POST "https://<api-de-su-entidad>/api/v1/storage/upload" \
  -H "Authorization: Bearer $ORPYCA_CREDENCIAL" -F "file=@oficio.pdf"

Exige permite_subida y el permiso de la persona para subir. Con techo_crud 1 y subida activa se pueden subir bytes, pero vincularlos a un documento exige una escritura que ese techo no permite.

Errores de conexión¶

Respuesta	Causa	Qué hacer
`401 credencial_asistente_fuera_de_alcance`	Se usó en una ruta que no es del MCP ni de subida	Corregir la URL
`401 credencial_asistente_fuera_de_red`	La red de origen no está en `cidr_permitidos`	Revisar las redes o emitir otra
`401 invalid_token`	Credencial vencida, revocada o mal copiada, cuenta dada de baja o entidad con el permiso apagado	Revisar Mi perfil; si sigue vigente, preguntar al administrador
`403 permiso_insuficiente`	Lo pedido supera el permiso o el techo; `motivo` dice cuál	Subir el techo emitiendo otra, o hacerlo en pantalla
`403 sesion_requerida`	Acto de peldaño 4	Abrir `url_aprobacion`
`409 propuesta_consumida` / `410 propuesta_expirada`	Ya se usó o venció	Preparar el acto de nuevo

Revocar¶

Cada persona revoca las suyas en Mi perfil. Un administrador lo hace desde Administración → Usuarios (lectura con nivel 1; revocar con nivel 3 y motivo). La revocación tarda hasta 15 segundos. Nada se borra: la credencial queda marcada con quién y por qué.

Si una persona deja la entidad, dé de baja su cuenta en Administración → Usuarios («Dar de baja», con motivo). La baja corta la sesión abierta y toda petición posterior en menos de un minuto, y revoca sus credenciales de asistente, que no vuelven al reactivar la cuenta (se emiten nuevas). No se borra nada. Deshabilitar la cuenta en el proveedor de identidad, por sí solo, no corta nada: el corte está en la validación del token de la entidad.

Para quien despliega¶

Variables nuevas: ASISTENTE_PEPPER en auth-service (obligatoria; cambiarla invalida todas las credenciales) y REDIS_URL y APP_BASE_URL en mcp-server. El gateway y los servicios con identidad firmada se actualizan en el mismo despliegue. Detalle en Despliegue.