Llamar la API completa desde tu IA

Cualquier operación publicada de la API está al alcance de tu asistente, sin que nadie le haya escrito una herramienta a medida. Lo hacen tres herramientas del conector que no están atadas a ningún recurso. Las demás están en Herramientas del conector.

Cada operación que devuelve search_operations viene con su método, si escribe y si es destructiva. Destructiva es la que termina algo que no se puede recuperar. Con eso tu asistente distingue cuál de dos identificadores parecidos es el que borra.

La diferencia con las otras herramientas está en el diseño, no en los permisos. Las otras contestan en una sola llamada lo que una persona pregunta en palabras, y devuelven una respuesta ya ordenada. Estas tres contestan lo que pregunta una integración: un recurso campo por campo, una lista con los filtros exactos de la API, o algo que todavía no tiene herramienta propia.

Una conversación completa

Primero, qué hay:

// search_operations  { "query": "sucursales" }
{
  "total": 2,
  "returned": 2,
  "tags": ["Leads", "Locations", "Pipelines", "Public Stock", "Vehicles", "…"],
  "operations": [
    {
      "operation_id": "locations_list",
      "method": "GET",
      "path": "/locations",
      "tag": "Locations",
      "tier": "beta",
      "summary": "List locations (branches / stores / clinics / offices)",
      "scopes": ["tenant:read"]
    },
    {
      "operation_id": "location_get",
      "method": "GET",
      "path": "/locations/{id}",
      "tag": "Locations",
      "tier": "beta",
      "summary": "Get a location (uuid or B- display id)",
      "scopes": ["tenant:read"]
    }
  ]
}

Después, cómo se llama:

// describe_operation  { "operation_id": "location_get" }
{
  "operation_id": "location_get",
  "aliases": ["GET /locations/{id}"],
  "method": "GET",
  "path": "/locations/{id}",
  "url": "/api/v1/locations/{id}",
  "tier": "beta",
  "scopes": ["tenant:read"],
  "parameters": [
    { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
  ],
  "responses": { "200": { "description": "Location" } }
}

Y por último, la llamada:

// call_operation  { "operation_id": "location_get", "params": { "id": "B-2" } }
{
  "data": {
    "id": "6812d9f0-9bed-44b5-91df-4e5b90941f6b",
    "display_id": "B-2",
    "name": "Sucursal Norte",
    "…": "…"
  }
}

Los parámetros de ruta y los de consulta van juntos en params, con los nombres que dice describe_operation. Un nombre que la operación no declara se rechaza, no se ignora. Un filtro que se cae en silencio devuelve más filas de las que pediste, y tu asistente te las contaría como filtradas.

Los identificadores

locations_list, location_get, webhook_deliveries_list. Se leen, y son estables. La forma cruda "GET /locations/{id}", la misma que aparece en aliases, también sirve si vienes leyendo el documento OpenAPI.

Qué alcanzan, y qué no

Están dentro las operaciones publicadas, las que la API promete y versiona, y nada más.

Escribir

Si al autorizar la aplicación activaste un área, por ejemplo Leads, las operaciones de escritura de esa área aparecen en search_operations y call_operation las ejecuta. El cuerpo va en body, y describe_operation te dice qué campos acepta.

// call_operation
{
  "operation_id": "leads_create",
  "body": { "contact_id": "…", "pipeline_id": "…", "title": "Consulta por SUV" }
}

Las operaciones destructivas vienen marcadas ("destructive": true) en la lista y en el contrato. La herramienta se anuncia como destructiva ante tu cliente MCP, y por eso Claude te pregunta antes de ejecutarla. Es una señal para que decidas: quien decide de verdad es la API, con los permisos de tu credencial.

Mandarle un mensaje a un cliente tuyo tiene su propia área, Mensajes a clientes, y sus propias reglas. Un contacto a la vez sale directo. A partir del cuarto contacto distinto en diez minutos, el mensaje queda esperando aprobación. Ver Enviar mensajes.

Es tu misma credencial

call_operation no es un atajo por dentro de Vitrina: arma la solicitud HTTP que habrías hecho tú y la manda por la misma API. La credencial es la misma con la que tu asistente se conectó. Se aplica todo lo de siempre, una vez y desde el mismo lugar: autenticación, permisos, validación, visibilidad, auditoría y límites de uso. La visibilidad de registros y de sucursales es la de quien autorizó.

Por eso la respuesta es idéntica, byte a byte, a la que te habría dado la API llamada directamente con esa credencial. Y por eso un error llega con el texto exacto de la API:

GET /vehicles answered 400: {"error":{"code":"VALIDATION_ERROR",
  "message":"Request validation failed",
  "details":{"query":[{"path":"sort","message":"Invalid enum value…"}]},
  "requestId":"f7451f40-cf32-4a7f-aefc-77d791ff6afb"}}

Ese requestId es el mismo que aparece en los registros del servidor, así que sirve para preguntar qué pasó.

Qué devuelve de una persona

Depende del rubro del workspace: en uno de ellos la identidad viaja recortada por defecto.

Archivos

Una operación que responde un archivo (una exportación, el contenido de un adjunto) no manda los bytes por MCP. Tu asistente recibe la descripción y el tamaño:

{
  "operation_id": "vehicles_export_list",
  "status": 200,
  "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size_bytes": 7746,
  "note": "Binary response — call this operation over HTTPS to download it; the bytes are not returned over MCP."
}

Un archivo binario dentro de una conversación es texto ilegible que ocupa todo el contexto. Para bajarlo, la operación sigue estando en la API.