Herramientas

Las tres capas

Antes de usar estos tools conviene tener clara la separación, porque es la fuente de casi todos los errores:

1. El catálogo del workspace — todo lo que existe y se puede usar. list_workspace_tools.
2. La conexión con un agente — lo que hace que un agente concreto pueda llamar una herramienta. connect_agent_tool.
3. Los conectores — lo que crea entradas en el catálogo. connect_mcp_server y create_api_tool.

Instalar una herramienta en el workspace no se la da a ningún agente. Desconectarla de un agente no la borra del workspace.

connect_mcp_server        → el servidor y sus herramientas quedan en el catálogo
list_workspace_tools      → obtienes los toolId
connect_agent_tool        → el agente ya puede llamarlas

Documentación REST completa en Herramientas .

Catálogo del workspace

list_workspace_tools

Devuelve id (el toolId), name, description, kind, parameters y el origen de cada herramienta.

get_workspace_tool

Igual que un elemento de la lista, con el JSON Schema completo de los parámetros.

Herramientas de un agente

list_agent_tools

Sólo las conexiones con status: "active" se le pasan al modelo en tiempo de ejecución. Una entrada con toolExists: false es una conexión huérfana: la herramienta del catálogo fue eliminada.

list_available_agent_tools

Devuelve el catálogo completo con isConnected y connectionStatus. Úsalo antes de conectar para no chocar con un 409.

connect_agent_tool

Devuelve 409 si ya estaba conectada — en ese caso usa update_agent_tool_status.

update_agent_tool_status

Desactivar es la forma reversible de quitarle una herramienta al agente. Activar una que no estaba conectada la conecta, así que el tool es idempotente.

disconnect_agent_tool

Elimina la conexión. No borra la herramienta del catálogo ni afecta a otros agentes.

Servidores MCP

preview_mcp_server

Se conecta al servidor y lista sus herramientas sin guardar nada. Llámalo antes de connect_mcp_server.

Formas de auth:

Los name que devuelve son los nombres originales del servidor: son los que se pasan como tools a connect_mcp_server y sync_mcp_server_tools.

list_mcp_servers

status puede ser connected, pending_auth, needs_reauth o error. Las credenciales nunca se devuelven.

get_mcp_server

Incluye discoveredTools (lo que ofrece el servidor, con un flag installed) e installedTools (lo que está en el catálogo, con su toolId).

connect_mcp_server

{
  "name": "connect_mcp_server",
  "arguments": {
    "name": "Linear",
    "url": "https://mcp.linear.app/mcp",
    "auth": { "type": "bearer", "token": "lin_api_xxx" },
    "tools": ["create_issue", "search_issues"]
  }
}

Devuelve installedToolIds, que son los toolId listos para connect_agent_tool.

refresh_mcp_server

Vuelve a descubrir herramientas y actualiza los esquemas de las instaladas. No instala las nuevas: aparecen con installed: false hasta que las agregues con sync_mcp_server_tools.

start_mcp_server_oauth

Devuelve authorizeUrl; una persona debe abrirla en el navegador. El callback guarda los tokens cifrados.

sync_mcp_server_tools

delete_mcp_server

Elimina el servidor, sus credenciales, sus herramientas y las conexiones que tuvieran con cualquier agente.

APIs personalizadas

Una API personalizada convierte un endpoint HTTP en una herramienta. Tiene dos partes: request describe la llamada con marcadores {{nombre}}, y variables declara quién rellena cada uno.

El esquema que ve el modelo se deriva de las variables ai al habilitarla. Por eso la description de cada variable es obligatoria: es lo que el modelo lee.

Ciclo de vida: draft → enabled → paused. Sólo en enabled existe en el catálogo.

list_api_tools

get_api_tool

Las credenciales y constantes write-only se devuelven como "[REDACTED]"; nunca entran al contexto del modelo.

create_api_tool

{
  "name": "create_api_tool",
  "arguments": {
    "name": "order_lookup",
    "description": "Consulta el estado de un pedido por su folio. Úsala cuando el cliente pregunte dónde va su pedido.",
    "request": {
      "method": "GET",
      "url": "https://api.tienda.com/orders/{{orderId}}",
      "auth": { "type": "bearer", "token": "sk_live_xxx" }
    },
    "variables": [
      {
        "name": "orderId",
        "type": "string",
        "description": "Folio del pedido, tal como aparece en el correo de confirmación.",
        "required": true
      }
    ]
  }
}

Nace como borrador. Pruébala con test_api_tool y publícala con enable_api_tool.

update_api_tool

Mismos campos que create_api_tool pero todos opcionales, más integrationId. Los arrays (variables, request.headers, request.params) se reemplazan completos, no se fusionan elemento por elemento.

test_api_tool

Empieza con dryRun: true para verificar las sustituciones antes de golpear la API real. Un fallo de la API remota no es un error del tool: se reporta en data.outcome y data.httpStatus.

enable_api_tool

Publica la herramienta en el catálogo y devuelve el toolId para connect_agent_tool. Falla con 400 si alguna variable visible para el modelo no tiene descripción.

pause_api_tool

Retira la herramienta del catálogo conservando su configuración.

delete_api_tool

Elimina la herramienta definitivamente. Si sólo quieres apagarla, usa pause_api_tool.

Endpoints REST sin tool MCP

• Instalar apps de primera parte (kind: "integration") se hace desde el panel. Una vez instaladas, sus herramientas aparecen en list_workspace_tools y se conectan igual que cualquier otra.