Herramientas de Agente

Conectar una herramienta a un agente es lo que hace que el modelo pueda llamarla. La herramienta ya debe existir en el catálogo del workspace ; estos endpoints sólo administran la relación.

Una misma herramienta puede estar conectada a varios agentes a la vez, y conectarla o desconectarla nunca modifica la herramienta ni el servidor MCP / API que la respalda.

Hay dos formas de quitarle una herramienta a un agente:

Desactivar (PATCH con status: "inactive") conserva la conexión pero el modelo deja de verla. Es reversible con un solo PATCH.
Desconectar (DELETE) elimina la relación. Volver atrás requiere un POST nuevo.

En tiempo de ejecución el agente sólo recibe las herramientas con status: "active". Desactivar es lo que quieres para apagar una herramienta temporalmente.

Listar Herramientas del Agente

GET https://api.platica.mx/v1/agents/{agentId}/tools

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente	✓

Respuesta

{
  "count": 2,
  "tools": [
    {
      "registrationId": "pQ7xLm2NvKdR",
      "toolId": "8fK2mQpLxT4vNbRc",
      "name": "mcp_create_issue_a1b2c3",
      "description": "Create a new issue in Linear",
      "kind": "mcp",
      "status": "active",
      "toolExists": true,
      "registeredAt": "2026-07-14T18:05:22.881Z"
    },
    {
      "registrationId": "Wc4TnB9yHsEz",
      "toolId": "RuzoaswTBBrhutHyKYZn",
      "name": "api_order_lookup",
      "description": "Consulta el estado de un pedido por su folio.",
      "kind": "api",
      "status": "inactive",
      "toolExists": true,
      "registeredAt": "2026-07-12T09:20:07.554Z"
    }
  ]
}

Campo	Tipo	Descripción
`registrationId`	string	Identificador interno de la conexión. Informativo — todas las operaciones se hacen con `toolId`.
`toolId`	string \| null	Herramienta del catálogo a la que apunta la conexión.
`name`, `description`, `kind`	string \| null	Copiados del catálogo al momento de leer. `null` si la herramienta ya no existe.
`status`	string	`active` o `inactive`.
`toolExists`	boolean	`false` cuando la herramienta del catálogo fue eliminada y quedó una conexión huérfana.
`registeredAt`	string \| null	ISO 8601.

Advertencia

Si ves una entrada con toolExists: false, la herramienta a la que apuntaba se eliminó del workspace y la conexión quedó huérfana. No afecta al agente, pero puedes limpiarla con DELETE /v1/agents/{agentId}/tools/{toolId}.

Listar Herramientas Conectables

Devuelve el catálogo completo del workspace, marcando cuáles ya están conectadas a este agente. Es la forma de armar un selector sin duplicar conexiones.

GET https://api.platica.mx/v1/agents/{agentId}/tools/available

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente	✓

Parámetros de consulta

Parámetro	Tipo	Descripción	Requerido
`kind`	string	Filtra por origen: `mcp`, `api`, `integration` o `legacy`	—
`workspace`	string	Requerido para API keys multi-workspace	—

Respuesta

Cada elemento tiene los mismos campos que el catálogo más dos:

{
  "count": 1,
  "tools": [
    {
      "id": "8fK2mQpLxT4vNbRc",
      "name": "mcp_create_issue_a1b2c3",
      "description": "Create a new issue in Linear",
      "kind": "mcp",
      "parameters": { "type": "object", "properties": {} },
      "status": "active",
      "mcpId": "QZPHpckDPC58JIVLQA3Z",
      "mcpToolName": "create_issue",
      "mcpName": "Linear",
      "mcpStatus": "connected",
      "integrationId": null,
      "integrationName": null,
      "integrationStatus": null,
      "installationId": null,
      "providerId": null,
      "providerToolName": null,
      "createdAt": "2026-07-14T18:02:11.410Z",
      "updatedAt": "2026-07-14T18:02:11.410Z",
      "isConnected": true,
      "connectionStatus": "active"
    }
  ]
}

Campo	Tipo	Descripción
`isConnected`	boolean	Si el agente ya tiene esta herramienta conectada.
`connectionStatus`	string \| null	`active`, `inactive`, o `null` si no está conectada.

Conectar Herramienta

POST https://api.platica.mx/v1/agents/{agentId}/tools

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente	✓

Cuerpo de la solicitud

{
  "toolId": "8fK2mQpLxT4vNbRc",
  "status": "active"
}

Parámetro	Tipo	Descripción	Requerido	Default
`toolId`	string	Identificador de la herramienta en el catálogo	✓	—
`status`	string	`"active"` o `"inactive"`. Con `"inactive"` queda conectada pero el modelo no la ve	—	`"active"`

Respuesta

{
  "status": "success",
  "message": "Tool connected successfully",
  "data": {
    "connection": {
      "registrationId": "pQ7xLm2NvKdR",
      "toolId": "8fK2mQpLxT4vNbRc",
      "name": "mcp_create_issue_a1b2c3",
      "description": "Create a new issue in Linear",
      "kind": "mcp",
      "status": "active",
      "toolExists": true,
      "registeredAt": "2026-07-14T18:05:22.881Z"
    }
  }
}

Errores

Status	Causa
`404`	El agente no existe, o la herramienta no está en el catálogo del workspace
`409`	La herramienta ya está conectada a este agente — usa `PATCH` para cambiarle el estado

Activar o Desactivar Herramienta

PATCH https://api.platica.mx/v1/agents/{agentId}/tools/{toolId}

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente	✓
`toolId`	string	Identificador de la herramienta en el catálogo	✓

Cuerpo de la solicitud

{
  "status": "inactive"
}

Parámetro	Tipo	Descripción	Requerido
`status`	string	`"active"` o `"inactive"`	✓

Respuesta

{
  "status": "success",
  "message": "Tool status updated to inactive",
  "data": {
    "connection": {
      "registrationId": "pQ7xLm2NvKdR",
      "toolId": "8fK2mQpLxT4vNbRc",
      "name": "mcp_create_issue_a1b2c3",
      "description": "Create a new issue in Linear",
      "kind": "mcp",
      "status": "inactive",
      "toolExists": true,
      "registeredAt": "2026-07-14T18:05:22.881Z"
    }
  }
}

Activar una herramienta que no estaba conectada la conecta, así que este endpoint es idempotente: pedir status: "active" siempre deja al agente con la herramienta activa, haya estado conectada antes o no.

Errores

Status	Causa
`404`	El agente o la herramienta no existen, o se pidió `"inactive"` sobre una herramienta que no está conectada

Desconectar Herramienta

Elimina la conexión. La herramienta sigue en el catálogo y otros agentes que la tengan no se ven afectados.

DELETE https://api.platica.mx/v1/agents/{agentId}/tools/{toolId}

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`agentId`	string	Identificador del agente	✓
`toolId`	string	Identificador de la herramienta en el catálogo	✓

Respuesta

{
  "status": "success",
  "message": "Tool disconnected successfully",
  "data": {
    "toolId": "8fK2mQpLxT4vNbRc",
    "removedRegistrations": 1
  }
}

removedRegistrations normalmente es 1. Puede ser mayor si el agente tenía conexiones duplicadas a la misma herramienta, en cuyo caso se eliminan todas.

Errores

Status	Causa
`404`	El agente no existe o la herramienta no está conectada

Anterior Catálogo del Workspace Siguiente Servidores MCP