Subir archivos a una ficha por MCP

file_uploads («Subir archivos») sube un archivo del disco de la persona a la ficha que lo pide: el justificante de un gasto, un adjunto de una factura o de un presupuesto, la imagen de un proyecto. Pasa por el permiso y el plan del módulo de esa ficha, igual que la subida de la aplicación en esa pantalla, y no necesita el Gestor de archivos.

Úsala cuando otra herramienta de tu servidor pida un fileId y el archivo esté en el disco. Antes había que subirlo con fm_files_manage del servidor utilia-crm, que exige el Gestor de archivos en el plan y su permiso. Para guardar un archivo en una carpeta del Gestor, esa sigue siendo la herramienta.

Requisitos

• Servidor. Está en utilia-finance, utilia-work, utilia-crm, utilia-marketing y utilia-rrhh, cada uno con sus propios destinos. No está en el servidor de Chat, que no tiene fichas a las que subir, ni en el de desarrolladores, ni en los conectores de los directorios de Claude y ChatGPT.
• Scope. No hay scopes nuevos. La conexión necesita el scope de escritura de la operación que va a usar el archivo, o un conjunto que lo incluya: con finance:payments:create subes un documento para digitalizar, pero no el justificante de un gasto, que pide finance:expenses:update. La herramienta aparece en tools/list si la conexión puede abrir alguno de los destinos de ese servidor.
• Permiso. Los del destino, todos a la vez, con el alcance de editar esa ficha: los mismos que pide la aplicación para subir ahí. Están en Permisos y scopes de cada destino.
• Plan. El aplicativo del destino: Finanzas, Gestión de proyectos, CRM, Marketing o RRHH. El Gestor de archivos no hace falta.
• Cuenta en pausa. Si la cuenta de la empresa está en pausa, solo funcionan list y abort_upload.

Cómo se sube

Son tres pasos, reservar, enviar el archivo y confirmar, y después el fileId se pasa a la operación del destino. El archivo nunca viaja dentro de la llamada.

La herramienta recibe siempre operation y, según la operación, estos parámetros:

operationstringobligatorio

request_upload, confirm_upload, abort_upload, create_upload_link o list.

destinationobject

En request_upload y create_upload_link, obligatorio; en list, filtra. type: el destino. id: el identificador de la ficha, salvo en los destinos que no la llevan.

filesobject[]

request_upload: de 1 a 20 archivos, cada uno con fileName, fileSize (los bytes exactos) y, si lo sabes, mimeType.

fileIdsstring[]

confirm_upload y abort_upload: de 1 a 20 fileId de request_upload.

Reservar la subida

{
  "name": "file_uploads",
  "arguments": {
    "operation": "request_upload",
    "destination": { "type": "expense_document", "id": "ckexp0142example" },
    "files": [
      { "fileName": "ticket-gasolinera.pdf", "fileSize": 184233, "mimeType": "application/pdf" }
    ]
  }
}

La respuesta trae el destino tal como lo verá la persona y, por cada archivo, su fileId y sus dos direcciones:

{
  "success": true,
  "destination": {
    "type": "expense_document",
    "id": "ckexp0142example",
    "label": "Justificante del gasto",
    "recordLabel": "GAS-2026-00142",
    "acceptedMimeTypes": ["application/pdf", "image/jpeg", "image/png", "image/webp"],
    "maxBytes": 10485760
  },
  "files": [
    {
      "fileId": "ckfile0001example",
      "fileName": "ticket-gasolinera.pdf",
      "method": "PUT",
      "uploadUrl": "https://…",
      "relayUploadUrl": "https://os.utilia.ai/api/files/relay-upload/…",
      "headers": { "Content-Type": "application/pdf" },
      "mimeType": "application/pdf",
      "expiresInSeconds": 900
    }
  ],
  "nextStep": "Envía cada fichero con un PUT a su uploadUrl, con su Content-Type (…). Si el PUT a uploadUrl falla por la red, repítelo a relayUploadUrl; si tu entorno no puede hacer peticiones, pide a la persona que lo suba con create_upload_link. Después llama a file_uploads(operation: \"confirm_upload\", fileIds: [...]) con los fileId de files."
}

Cada archivo va por su cuenta: el que no cabe en el destino por su tipo o su tamaño sale en rejected, con su errorCode, y no impide reservar los demás. success llega a false solo si no se ha reservado ninguno. recordLabel es el número de la ficha, nunca un título libre, y llega a null si no lo tiene, como una factura en borrador.

Enviar el archivo

Haz un PUT del archivo a su uploadUrl, con las cabeceras de headers, antes de que pasen los 15 minutos:

curl --fail -sS -T "./ticket-gasolinera.pdf" \
  -H "Content-Type: application/pdf" \
  "<uploadUrl>"

Si el PUT no llega al almacén, tienes dos salidas, que se explican en Si el PUT no llega.

Confirmar y usar el fileId

confirm_upload comprueba que el archivo ha llegado y mide su tamaño y su tipo reales. Si no caben en el destino, lo borra y lo devuelve en failed con su errorCode. Lo que cabe sale en confirmed, y nextStep nombra la operación que recibe ese fileId:

{
  "success": true,
  "confirmed": [
    {
      "fileId": "ckfile0001example",
      "fileName": "ticket-gasolinera.pdf",
      "size": 184233,
      "mimeType": "application/pdf",
      "destination": { "type": "expense_document", "id": "ckexp0142example" }
    }
  ],
  "nextStep": "Pasa cada fileId a expenses(operation: \"document_attach\") con la ficha \"ckexp0142example\"; si esa operación pide confirm, ponlo a true solo cuando la persona lo haya confirmado. Cada fileId vale 24 horas y solo para ese destino."
}

La operación del destino recibe el fileId con su contrato de siempre, también su confirm si lo pide. Con un archivo subido así, se salta solo las puertas del Gestor de archivos (verlo, tenerlo en el plan y el scope de lectura de Archivos) y aplica todas las suyas.

Destinos de cada servidor

destination.type solo admite los destinos del servidor al que llamas: el enum de cada copia de la herramienta trae los suyos. Uno de otro servidor responde UPLOAD_DESTINATION_NOT_IN_SERVER, con el servidor donde vive.

destination.id es el identificador interno de la ficha, el que devuelven get y list: el número de un gasto no sirve. En issue_attachment y project_image vale también la clave de la tarea o del proyecto. Si falta en un destino que lo lleva, o sobra en uno que no, la respuesta es UPLOAD_DESTINATION_RECORD_REQUIRED. En los destinos de Gestión de proyectos, label usa los nombres del perfil de trabajo: en Agencia, «Adjunto de un entregable» o «Logotipo o portada de la cuenta».

Permisos y scopes de cada destino

Cada destino pasa sus puertas en este orden al reservar, al confirmar, al crear el enlace y otra vez cuando la operación usa el archivo:

La ficha se mira al final, así que una conexión sin el scope no llega a saber si existe. Una ficha que no existe y una que queda fuera de tu alcance dan la misma respuesta.

project_image pide FILE_MANAGER_UPLOAD porque es el permiso con el que la aplicación sube esa imagen, pero no el Gestor de archivos en el plan. confirm_upload, abort_upload y list piden los mismos scopes: solo ves, confirmas y liberas subidas de los destinos que tu conexión puede abrir, y las demás responden como si no existieran. abort_upload no pide el permiso del destino, porque solo libera lo tuyo.

Usar el fileId en su destino

Un fileId de file_uploads vale solo para el destino y la ficha para los que se reservó, una sola vez y durante 24 horas. En otra operación o con otra ficha, la respuesta es UPLOAD_DESTINATION_MISMATCH (409), aunque la persona tenga permiso sobre el Gestor de archivos: hay que subirlo otra vez con el destino que toca. Un fileId del Gestor sigue igual que siempre, con sus puertas.

Cada operación guarda el archivo como lo hace la aplicación en esa pantalla:

• Mismo archivo. El justificante del gasto, el documento para digitalizar, la imagen del proyecto y el adjunto del presupuesto se guardan tal cual, sin copia.
• Copia. En los demás, la operación guarda una copia con el mismo servicio que la subida de la aplicación y la subida de paso se borra. Un adjunto de una factura o de un gasto queda como subido a la ficha, no como un archivo del Gestor enlazado: al quitarlo pasa 30 días por «Eliminados recientemente». El de un elemento de trabajo se adjunta siempre como copia, nunca vinculado.
• Presupuesto. El adjunto nace solo para el equipo: el cliente no lo ve hasta que se comparte, desde la ficha del presupuesto en la aplicación o con crm_budget_files update_attachment (visibility y confirm: true; sin confirm es un ensayo que no cambia nada). Por MCP, todo link_attachment nace así, también con un archivo del Gestor, y list_attachments y get_attachment devuelven visibility. La respuesta lo recuerda en notice.
• Proyecto. La imagen se pone con projects update, con el mismo proyecto en el destino; el mismo fileId vale para logoFileId o para coverFileId.
• Política de desconexión. Se copia a la carpeta del protocolo de RRHH y pasa a ser la vigente.

Lo que no se usa no se queda guardado:

list devuelve tus subidas sin usar de las últimas 24 horas, como mucho 50, con fileId, fileName, size, mimeType, status (reserved o confirmed), via (mcp o link), destination y createdAt. Admite destination para filtrar. Sirve para recuperar una reserva olvidada y para conocer lo que la persona subió con un enlace.

Si el PUT no llega

Algunos entornos, como el de código de Claude, bloquean la dirección del almacén, y otros, como ChatGPT en la web, no pueden hacer peticiones con un archivo. Para los dos casos hay salida:

relayUploadUrl llega con cada archivo de request_upload. Es el mismo PUT, con el mismo método y las mismas cabeceras, a https://os.utilia.ai/api/files/relay-upload/…. Vale una sola vez y para ese archivo, caduca con la reserva a los 15 minutos y exige que Content-Length sea el tamaño exacto reservado. Después se confirma como siempre. Sus errores están en Subir un archivo cuando el PUT no llega.

create_upload_link recibe destination, con su id si lo lleva, y devuelve uploadLink: url, expiresAt, destination, maxFiles y maxFileBytes. La persona abre el enlace con su sesión de UTILIA OS, ve para qué ficha es y sube los archivos, con los tipos y el tamaño del destino; cada archivo pasa las mismas puertas. Cuando diga que lo ha subido, list con el mismo destination te da los fileId, ya confirmados y con via: "link", y los pasas a la operación del destino.

Solo abre el enlace quien lo pidió, y cada persona puede tener 10 enlaces vivos. Si tu conexión no puede enviar archivos y pides una reserva, la respuesta trae en hint la pista de liberarla con abort_upload y pedir el enlace con el mismo destino.

Límites

Cada destino tiene además su tope de archivos por llamada, de tamaño y de tipos, que es el mismo en request_upload y en el enlace para la persona:

El tipo se comprueba dos veces: al reservar, con el que declaras, y al confirmar, con el del archivo que ha llegado.

Errores

Todos llegan con isError: true, el código en details.errorCode y una pista para el asistente en hint. En request_upload, confirm_upload y abort_upload, un archivo que falla no tumba la llamada: sale en rejected, failed o notReleased con su errorCode.

Para subir a una carpeta del Gestor de archivos, a un lead, un cliente, un contacto o una oportunidad, las herramientas son fm_files_manage y crm_files_management del servidor utilia-crm, con las mismas dos salidas; lo explica Subir un archivo cuando el PUT no llega.