Manual para agentes de IA

Una puerta segura para que tu agente entienda Gandeo.

Conecta un agente a los datos operativos de una explotación de forma autenticada, acotada y auditable. Esta página es pública, no contiene secretos y está escrita para que una persona o un agente pueda empezar sin contexto adicional.

SSE + JSON-RPC1.3.0Leer como texto plano →

connection brief ready

endpoint

https://app.gandeo.com/api/mcp

authorization

Bearer gandeo_mcp_…

first call

describe_access()

El agente abre el stream SSE, recibe un sessionId y envía JSON-RPC por POST a esa sesión.

01 / conexión

Conecta el agente en cuatro pasos

01
El propietario o administrador crea una clave en Configuración > Developer Settings. Empieza con Solo lectura.
02
Guarda el token gandeo_mcp_* en el gestor de secretos del agente. Gandeo no vuelve a mostrarlo. Developer Settings también te ofrece un prompt listo para copiar y pegar en la IA.
03
Configura el servidor MCP con https://app.gandeo.com/api/mcp y el header Authorization: Bearer <TOKEN>.
04
Usa el transporte SSE: abre un GET autenticado, lee el evento endpoint y envía los mensajes JSON-RPC por POST a la URL que incluya sessionId.

Configuración de cliente MCPjson

{
  "mcpServers": {
    "gandeo": {
      "url": "https://app.gandeo.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

Abrir el stream SSEbash

BASE_URL="https://app.gandeo.com/api/mcp"
TOKEN="gandeo_mcp_..."

# Mantén esta conexión abierta. La respuesta SSE incluye:
# event: endpoint
# data: /api/mcp?sessionId=<SESSION_ID>
curl -N \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL"

Inicialización JSON-RPC

Después de recibir el endpoint con sessionId, envía el mensaje initialize por POST. El POST devuelve 202 y la respuesta llega por el stream.

curl -i -X POST "$BASE_URL?sessionId=<SESSION_ID>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "mi-agente", "version": "1.0.0"}
    }
  }'

02 / control de acceso

El token define hasta dónde puede llegar el agente

Solo lectura

read

Consultar explotaciones, animales, leche, derivados, documentos, economía, sanidad, reproducción, pesadas, pienso, parcelas, calendario, ayudas, notificaciones y auditoría.

describe_access, list_* y get_farm_snapshot

Lectura y escritura

write

Todo lo anterior, además de guardar borradores de producción/analíticas de leche, subir originales y marcar notificaciones propias como leídas. Los datos definitivos se confirman en la web de Gandeo.

read + record_milk_production, record_milk_sample, upload_document, update_record (notifications.read_at)

Administrador

admin

Las mismas operaciones seguras que write. No habilita borrados físicos ni confirmación de datos de negocio desde una IA.

write; delete_record bloqueado

03 / contrato

Herramientas disponibles

Llama primero a describe_access. El esquema que expone el servidor y esa respuesta son la fuente de verdad si esta página y el servidor divergen.

HerramientaPermisoEntrada y uso

describe_accessread

Sin argumentos. Devuelve el nivel efectivo del token, la explotación permitida y las tablas disponibles. Llámala primero.

list_farmsread

Sin argumentos. Devuelve la explotación asociada al token.

list_animalsread

farm_id, limit opcional. Lista animales activos con sus datos principales.

list_medicationsread

farm_id. Lista el catálogo de medicamentos de la explotación.

list_recordsread

farm_id, table, limit opcional. Consulta una tabla permitida. La tabla y los campos válidos se descubren con describe_access y los esquemas MCP.

get_farm_snapshotread

farm_id, limit_per_table opcional. Devuelve una fotografía resumida de los módulos principales. Úsala para una visión general.

create_recordwrite

farm_id, table, data. Bloqueada. Usa un borrador admitido o el formulario web de su módulo para revisar y confirmar.

update_recordwrite

farm_id, table, id, data. Solo admite marcar una notificación propia como leída (table=notifications, data={read_at:...}). Las demás actualizaciones requieren confirmación web.

record_milk_productionwrite

farm_id, scope, liters, record_date, shift y referencias opcionales. Registra un control de tanque o animal con validación de lactación; queda como borrador.

record_milk_deliverywrite

farm_id, collected_at, liters, tank_ids y metadatos opcionales. Bloqueada: revisa y confirma la recogida en el formulario web de Gandeo.

manage_dairy_lactationwrite

farm_id, operation y los campos de apertura/transición. Bloqueada: las aperturas y transiciones de lactación se revisan y confirman en la web de Gandeo.

record_udder_healthwrite

farm_id, animal_id, occurred_at, observaciones y referencias opcionales. Bloqueada: revisa y confirma la observación y su separación de leche en la web de Gandeo.

record_milk_samplewrite

farm_id, context, sampled_at y resultados analíticos opcionales. Guarda una analítica con su origen como borrador revisable.

create_dairy_tankwrite

farm_id, name, capacity_liters y configuración opcional. Bloqueada: crea y confirma el tanque desde su formulario web en Gandeo.

delete_recordadmin

farm_id, table, id. Bloqueada para todas las tablas. Usa la papelera o el formulario del módulo en la web; MCP no elimina físicamente registros.

create_medicationwrite

farm_id, name y campos sanitarios opcionales. Bloqueada: añade y confirma medicamentos en el formulario web del catálogo sanitario.

lookup_cadastreread

province, municipality, cadastral_reference opcional, polygon opcional, parcel opcional. Consulta datos oficiales de parcelas rústicas en el Catastro (superficie, paraje, referencia y coordenadas GPS).

create_pasturewrite

farm_id, name y campos catastrales/operativos opcionales. Bloqueada: revisa y confirma los datos de la parcela en su formulario web de Gandeo.

upload_documentwrite

farm_id, file_name, mime_type, content_base64 y metadatos opcionales. Conserva el archivo original en la explotación y crea su registro documental.

Familias de datos

Explotación: farms, animals, lots, contacts
Documentos: documents, document_files, document_extractions
Economía: transactions, transaction_animals
Sanidad: medications, treatments
Leche: dairy_tanks, dairy_lactations, milk_production_records, milk_samples, milk_deliveries, milk_settlements, milk_exclusion_periods, udder_health_events, dairy_forecast_snapshots, dairy_cuaderno_entries
Derivados lácteos: dairy_products, dairy_batches, dairy_batch_milk_inputs, dairy_batch_ingredients, dairy_batch_outputs, dairy_inventory_movements
Reproducción: heat_detections, breeding_events, pregnancy_checks, births, birth_offspring
Peso: weight_records
Pienso: feed_products, feed_stock_movements
Planificación y Pastoreo: alerts, pastures, pasture_rotations, operational_units, operational_unit_pastures, pasture_sectors, grazing_occupations, field_activities, field_mowing_details, custom_calendar_events
Sistema: notifications, subsidy_farm_opportunity_matches, audit_events

No hay SQL libre

El agente solo puede usar las tablas y campos que el servidor incluye en sus listas blancas. No intentes conectarte directamente a Supabase.

04 / comportamiento

El flujo que debe seguir un buen agente

Descubre el permiso

Llama a describe_access y conserva el farm_id devuelto. No pidas otra explotación.

Lee antes de actuar

Para preguntas generales usa get_farm_snapshot. Para detalle, list_records o la herramienta específica.

Explica la fuente

Cita la tabla, el registro y la fecha cuando estén disponibles. Si faltan datos, dilo claramente.

Espera confirmación

Las herramientas de borrador no confirman datos. Para operaciones definitivas, dirige a su formulario web de Gandeo; una confirmación en el chat no desbloquea MCP.

Verifica el resultado

Después de una mutación, vuelve a consultar el registro y comunica cualquier error sin ocultarlo.

05 / guardrails

Reglas de seguridad y calidad

No hay SQL libre. No intentes acceder a Supabase, tablas no listadas ni rutas internas.

Cada token está ligado a una sola explotación mediante api_keys.farm_id. No se puede cambiar ese alcance enviando otro farm_id; para otra explotación hay que crear otra clave.

El rol del miembro puede reducir el permiso guardado en la clave: viewer no tiene MCP, member queda limitado a lectura y owner/admin puede usar el nivel concedido.

Las escrituras permitidas se limitan a borradores lecheros, originales documentales y lectura de notificaciones propias, con auditoría mcp.*. create_record y delete_record están bloqueados.

MCP solo guarda producción y analíticas lecheras como borrador; recogidas, lactaciones, ubre, tanques, medicamentos y parcelas requieren confirmación desde su formulario web de Gandeo. Ni write ni admin permiten saltarse esta condición.

No inventes animales, importes, tratamientos, fechas ni documentos. Si una extracción es incierta, presenta una propuesta y pide revisión.

No incluy nunca tokens gandeo_mcp_* en respuestas, logs, repositorios, prompts persistentes o documentación.

Usa Solo lectura por defecto. Eleva permisos solo cuando el caso de uso lo necesite y el usuario lo haya autorizado.

06 / diagnóstico

Si algo falla

401 Unauthorized

Comprueba Authorization: Bearer <TOKEN>, que la clave sigue vigente, la explotación está activa, el usuario conserva rol habilitado y su acceso comercial incluye mcp_api.

400 Missing sessionId

Primero abre el GET SSE y utiliza exactamente la ruta recibida en el evento endpoint.

404 Session not found

La conexión SSE se cerró o la petición POST llegó a otra instancia. Abre una sesión nueva y mantén vivo el GET.

Error de permisos

Llama a describe_access. El farm_id debe coincidir con el permitido y la operación debe estar cubierta por read, write o admin.

Siguiente paso

Crea una clave y deja que el agente descubra el resto.

La clave queda ligada a una sola explotación. Empieza con Solo lectura y revócala desde Developer Settings cuando ya no la necesites.

Abrir Developer Settings Descargar mcp.txt