Herramientas

Una herramienta es una función que un agente puede llamar durante una conversación: consultar un pedido, crear un ticket, agendar una cita. Platica las administra en tres capas, y entenderlas es lo único que necesitas para usar estos endpoints:

Los conectores crean herramientas. Hay dos: servidores MCP y APIs personalizadas .
El catálogo del workspace es la lista de todo lo que existe y se puede usar. Vive en /v1/tools .
La conexión con el agente es lo que hace que un agente concreto pueda llamarla. Vive en /v1/agents/{agentId}/tools .

Las tres son pasos separados a propósito: instalar una herramienta en el workspace no se la da a ningún agente, y desconectarla de un agente no la borra del workspace. Un flujo completo se ve así:

POST /v1/tools/mcp                       → conectas el servidor e instalas sus herramientas
GET  /v1/tools                           → ves los toolId del catálogo
POST /v1/agents/{agentId}/tools          → se la das al agente

Catálogo del workspace

Método	Endpoint	Descripción
`GET`	`/v1/tools`	Listar el catálogo (`?kind=&mcpId=&integrationId=`)
`GET`	`/v1/tools/{toolId}`	Obtener una herramienta con su esquema completo

Herramientas de un agente

Método	Endpoint	Descripción
`GET`	`/v1/agents/{agentId}/tools`	Listar las herramientas conectadas
`GET`	`/v1/agents/{agentId}/tools/available`	Listar el catálogo marcando cuáles ya están conectadas
`POST`	`/v1/agents/{agentId}/tools`	Conectar una herramienta
`PATCH`	`/v1/agents/{agentId}/tools/{toolId}`	Activar o desactivar la conexión
`DELETE`	`/v1/agents/{agentId}/tools/{toolId}`	Desconectar

Servidores MCP

Método	Endpoint	Descripción
`POST`	`/v1/tools/mcp/preview`	Ver qué herramientas expone un servidor, sin guardar nada
`GET`	`/v1/tools/mcp`	Listar los servidores conectados
`POST`	`/v1/tools/mcp`	Conectar un servidor e instalar sus herramientas
`GET`	`/v1/tools/mcp/{mcpId}`	Obtener un servidor con sus herramientas
`POST`	`/v1/tools/mcp/{mcpId}/oauth/start`	Iniciar o reiniciar la autorización OAuth
`POST`	`/v1/tools/mcp/{mcpId}/refresh`	Volver a descubrir herramientas y actualizar esquemas
`POST`	`/v1/tools/mcp/{mcpId}/tools/sync`	Definir qué herramientas quedan instaladas
`DELETE`	`/v1/tools/mcp/{mcpId}`	Desconectar el servidor y eliminar sus herramientas

APIs personalizadas

Método	Endpoint	Descripción
`GET`	`/v1/tools/apis`	Listar las APIs configuradas
`POST`	`/v1/tools/apis`	Crear una (nace como borrador)
`GET`	`/v1/tools/apis/{integrationId}`	Obtener la definición completa
`PATCH`	`/v1/tools/apis/{integrationId}`	Actualizar parcialmente
`POST`	`/v1/tools/apis/{integrationId}/test`	Probarla con valores de ejemplo
`POST`	`/v1/tools/apis/{integrationId}/enable`	Publicarla en el catálogo
`POST`	`/v1/tools/apis/{integrationId}/pause`	Retirarla del catálogo conservando la configuración
`DELETE`	`/v1/tools/apis/{integrationId}`	Eliminarla

Tipos de herramienta

El campo kind indica de dónde viene cada herramienta del catálogo:

`kind`	Origen	Se administra en
`mcp`	Instalada desde un servidor MCP	`/v1/tools/mcp`
`api`	API personalizada habilitada	`/v1/tools/apis`
`integration`	App de primera parte instalada desde el panel	Panel de Platica
`legacy`	Herramienta HTTP del editor clásico (nombre `request_*`)	Panel de Platica

Todos los tipos se conectan a un agente igual, con los mismos endpoints. Los conectores sólo se distinguen al crear la herramienta.

Estados

Hay dos estados independientes y es fácil confundirlos:

El estado de la conexión (active / inactive) determina si el agente ve la herramienta. Sólo las conexiones active se le pasan al modelo en tiempo de ejecución. Desactivar es reversible y conserva la conexión.
El estado de la fuente —status del servidor MCP, o draft / enabled / paused de una API personalizada— determina si la herramienta existe en el catálogo. Una API en draft o paused no tiene entrada de catálogo, así que no se le puede conectar a nadie.

Consejo

Para API keys con acceso a múltiples workspaces es necesario incluir ?workspace={workspaceId} en cualquier operación sobre /v1/tools/... y /v1/agents/{agentId}/tools/....

Permisos

Los endpoints bajo /v1/tools pertenecen al módulo integraciones del workspace; los de /v1/agents/{agentId}/tools al módulo agentes. Las API keys tienen acceso completo al workspace, así que esta distinción sólo aplica cuando un agente de Platica llama a la API con permisos delegados.

Anterior Base de Conocimientos Siguiente Catálogo del Workspace