Ir al contenido

Primeros pasos con los agentes de codificación con IA

La forma más rápida de conectarse está dentro del propio PlaidCloud: abra el menú del avatar (usuario) y elija Conecte su IA, seleccione el cliente que usa y siga los pasos que muestra, incluida la URL del servidor MCP de su espacio de trabajo, ya rellenada. Está disponible siempre que su espacio de trabajo tenga habilitada la autorización de IA. El resto de esta página, y las páginas por cliente que la siguen, siguen siendo la referencia: siga leyendo si no está en la interfaz web o desea tener el panorama completo de la autenticación y de lo que expone el servidor.

El Model Context Protocol es un estándar abierto para que los agentes de IA se comuniquen con herramientas y datos externos. PlaidCloud ejecuta un servidor MCP en cada espacio de trabajo que envuelve las mismas funciones auxiliares centrales que usa la API REST, agrupadas por intención (find, describe, upsert, run, organize), para que un agente pueda recorrer la superficie sin cargar más de 1000 nombres de métodos RPC de bajo nivel.

El servidor está en:

https://<your-workspace>.plaid.cloud/mcp

Reemplace <your-workspace> por el subdominio de su espacio de trabajo (el que use para iniciar sesión en la interfaz de PlaidCloud).

El catálogo cubre la mayor parte de la superficie cotidiana que necesita un agente:

  • Proyectos, flujos de trabajo, pasos: find/describe/upsert/run/organize, incluida la reejecución a nivel de paso y el historial de versiones.
  • Tablas, vistas, consultas: introspección de esquemas, ejecución de consultas, exportaciones, instantáneas, ramas. Las vistas son las mismas que ve en PlaidCloud, ya sea que las haya creado en el explorador de tablas o que las haya generado un flujo de trabajo.
  • Dimensiones: describir, buscar, upsert, versiones, administrar nodos, alias y propiedades.
  • Conexiones: buscar, upsert y probar conexiones con sistemas externos.
  • Lakehouse: ramas, instantáneas, operaciones de optimización y vacuum.
  • Identidad: miembros, grupos, sesiones, listas de distribución.
  • Documentos, paneles de control, UDF, editores, agentes, publicaciones: herramientas específicas de cada dominio.
  • Migración de flujos de trabajo: convierta exportaciones de Alteryx (alteryx_convert), KNIME (knime_convert), Prophecy (prophecy_convert) y Savant (savant_convert) preparadas en Document en flujos de trabajo de PlaidCloud, y coordine el trabajo de migración de portafolios.
  • Documentación de PlaidCloud: docs_search encuentra páginas de la documentación de PlaidCloud por palabra clave, y docs_fetch lee una página completa, para que su agente pueda comprobar cómo funciona una característica antes de crear con ella.
  • Registros de flujos de trabajo y seguimiento de ejecuciones: workflow_logs, workflow_run_status, workflow_job_track.

Cada herramienta devuelve un sobre uniforme {ok, data, next_cursor?, total?}; los errores usan {ok: false, error: {code, retryable, message, hint?}}. Las mutaciones aceptan dry_run=True para validar el plan sin escribir.

Los resultados de las herramientas son el mayor consumidor individual del contexto de un agente, por lo que las herramientas find y describe devuelven por omisión una porción modesta y le permiten ampliarla:

  • Filas. Un find devuelve 25 coincidencias por página (step_find devuelve 50). Una página limitada establece next_cursor, y las herramientas find además nombran la lista recortada en truncated; cualquiera de los dos significa “hay más”, no “eso es todo”. total siempre informa del recuento completo. Aumente limit o pagine con el cursor.
  • Columnas. Pase fields=['id', 'name', 'update_time'] para recibir solo esas columnas. Un nombre de campo que no aparece en ningún registro es un error que enumera los campos disponibles, no una omisión silenciosa, de modo que un error tipográfico falla de forma ruidosa en lugar de devolver en silencio menos de lo que pidió. Las herramientas que ofrecen conjuntos preestablecidos también aceptan field_set='minimal' | 'default' | 'full'; llame a mcp_introspect para ver qué parámetros acepta una herramienta determinada.
  • Recuento. count_only=True calcula el tamaño de un conjunto de resultados sin recuperarlo.

El spec que recibe una herramienta, como el de project_upsert o workflow_upsert, acepta solo los campos que enumera. Un campo que no reconoce se rechaza con un error que nombra el campo, en lugar de ignorarse y dejar que usted descubra después que no hizo nada. Corrija el nombre y envíe la solicitud de nuevo. workflow_upsert recibe la descripción de un flujo de trabajo como memo, y acepta description como otro nombre para ella.

mcp_batch agrupa varias llamadas a herramientas en una sola solicitud. Acepta como máximo 100 llamadas, ejecuta un número limitado de ellas a la vez y no se puede anidar dentro de otro mcp_batch ni de una receta; en su lugar, enumere las llamadas en un único lote plano, lo que no cuesta más enviar. Un lote que supera el límite se rechaza con un mensaje que lo nombra en lugar de recortarse silenciosamente; el límite acota el trabajo que puede iniciar una sola solicitud, no el total que puede hacer, así que divida un trabajo más grande en varios lotes.

La receta paginate_through_listing se detiene después de 200 páginas por alto que sea el max_pages que le pase, e informa partial: true cuando se detiene antes. Entre eso y su límite max_items, una sola llamada de paginación siempre termina.

Una receta rechaza una clave de params que no reconoce, y el mensaje enumera las claves que esa receta acepta, de modo que un parámetro opcional mal escrito falla de forma ruidosa en lugar de descartarse, lo que haría que la llamada respondiera en silencio una pregunta distinta de la que usted hizo. Llame a mcp_recipes(name=...) para ver las claves que acepta una receta determinada.

Un resultado grande cuyas filas llevan todas los mismos campos se devuelve orientado a columnas en lugar de como una lista de objetos, de modo que los nombres de los campos se envían una vez en lugar de una vez por fila:

{"_fmt": "cols", "cols": ["id", "name"], "rows": [["a1", "Sales"], ["b2", "Costs"]]}

La fila i es dict(zip(cols, rows[i])). Los resultados pequeños, y cualquier resultado cuyas filas no compartan un conjunto idéntico de campos, siguen siendo matrices ordinarias de objetos; por eso aparecen ambas formas, y el código que lee estas respuestas directamente debe manejar cada una. El sobre que las rodea no cambia, y ningún valor se convierte ni se redondea por el camino. A los agentes se les informa de esta forma cuando se conectan y la leen sin que usted tenga que indicarles nada; el ahorro es de alrededor del 30 % de los caracteres y de alrededor del 15 % del presupuesto de lectura de un agente en el tráfico típico de listados, lo que deja contexto disponible para su pregunta real. (Las dos cifras difieren porque a un modelo le resulta barato leer nombres de campo repetidos; el ahorro de caracteres siempre es el mayor de los dos.)

Para ver el catálogo en vivo, dirija a su agente al servidor y llame a mcp_introspect (sin argumentos): devuelve el número actual de herramientas, resúmenes por dominio y las firmas de los parámetros. Use mcp_recipes para ver guías habituales de varias herramientas (paginar listas grandes, instantánea y luego modificar, volver a ejecutar un paso fallido, etc.).

Cada herramienta upsert que establece etiquetas, para tablas, flujos de trabajo, pasos, proyectos, dimensiones, vistas, editores, UDF, conexiones y almacenes, recibe dos parámetros: labels agrega etiquetas y remove_labels las quita. Las demás etiquetas del objeto permanecen. Las eliminaciones se aplican antes que las adiciones, por lo que una sola llamada puede cambiar el nombre de una etiqueta:

{"remove_labels": ["01"], "labels": ["001"]}

Quitar una etiqueta que el objeto no tiene no hace nada.

Las herramientas de vistas trabajan con las vistas que ve en PlaidCloud:

  • view_find enumera las vistas, y view_describe devuelve una por ID o nombre.
  • view_upsert crea una vista o actualiza una existente en su lugar. Una actualización conserva el ID y las etiquetas de la vista, y puede cambiar solo sus etiquetas sin volver a enviar la consulta.
  • view_organize elimina, cambia el nombre, duplica y mueve vistas.
  • Escriba los parámetros de consulta como marcadores de posición %(name)s.

Las vistas comparten el árbol de carpetas de las tablas, así que use table_organize para administrar sus carpetas.

Creación de flujos de trabajo con pasos nativos

Sección titulada «Creación de flujos de trabajo con pasos nativos»

Una vez que sus datos están en PlaidCloud, se guía a su agente para que cree cada transformación con pasos nativos de tablas, como Table Extract, los pasos de combinación, Table Melt, Table Union All y Table Lookup, en lugar de con Extraer SQL. Un paso nativo sustituye sus variables en sus filtros y expresiones, y PlaidCloud genera su SQL para el almacén de su proyecto. Un paso Extraer SQL envía su consulta al almacén tal como está escrita: no sustituye ninguna variable, y su SQL está escrito para un solo almacén.

Su agente puede probar una configuración de Table Extract con query_run(mode='config') (la configuración que guardaría con step_upsert) y ver sus filas antes de guardar el paso. Cuando guarda un paso Extraer SQL, step_upsert devuelve una entrada prefer_native_steps en config_warnings que nombra los pasos nativos que debe usar en su lugar, y describe_step_operation incluye la misma nota. Extraer SQL sigue disponible para lo que ningún paso nativo puede expresar.

El servidor incluye un pequeño conjunto de iniciadores para las tareas que las personas piden por su nombre. Un cliente que admite indicaciones MCP las enumera y las ofrece como un menú (consulte la documentación de su cliente para saber dónde las coloca), de modo que usted elige la tarea en lugar de describir la secuencia de llamadas a herramientas que requiere:

Iniciador Qué le proporciona
Importar un archivo CSV a una tabla El archivo y, opcionalmente, el proyecto, la carpeta que lo contiene y un nombre para la tabla nueva
Explicar un cambio de costos La tabla de resultados y, opcionalmente, el proyecto y los dos períodos
Depurar un flujo de trabajo fallido El flujo de trabajo y, opcionalmente, el proyecto
Explorar los datos del proyecto Lo que busca y, opcionalmente, el proyecto

Cada uno es un mensaje inicial, no una orden: su agente lo lee y luego maneja las herramientas por sí mismo, de modo que puede editarlo o continuar la conversación desde ahí.

Importar un archivo sin conocer el modelo de objetos

Sección titulada «Importar un archivo sin conocer el modelo de objetos»

El iniciador de importación es el que más trabajo ahorra, porque el camino ingenuo requiere cuatro herramientas en el orden correcto (encontrar la cuenta de documentos, ir al archivo, crear la tabla de destino y luego ejecutar la importación), y una suposición errónea en cualquiera de ellas termina el flujo varias llamadas después.

Lee texto delimitado: CSV, TSV y similares. Un libro de Excel o un archivo Parquet se rechaza en lugar de leerse mal; traiga esos datos con el paso de importación correspondiente en un flujo de trabajo.

En su lugar, la guía bulk_import_csv recibe la cuenta por nombre y el archivo por nombre o ruta:

mcp_recipe_run(name='bulk_import_csv', params={
'project_id': '<project>',
'document_path': 'sales_2026.csv',
'document_account': 'Demo Data',
})

Resuelve la cuenta a su identificador, localiza el archivo, crea la tabla con las columnas y los tipos leídos del propio archivo y la carga, de modo que usted no proporciona ni un id de cuenta ni una especificación de columnas. table_name toma por omisión el nombre del archivo sin su extensión, y table_path la raíz del proyecto.

Indique la carpeta cuando la conozca ('document_path': 'raw/sales_2026.csv') y la búsqueda se limita a ella. Un archivo nombrado en una carpeta solo se busca en esa carpeta: un archivo con el mismo nombre más abajo se ofrece como una opción en lugar de importarse en su lugar.

Cuando un argumento es ambiguo, el resultado pregunta en lugar de adivinar:

{
"needs_choice": "document_account",
"question": "More than one document account is named 'Archive'. Which one?",
"candidates": [{"id": "...", "name": "Archive"}, {"id": "...", "name": "Archive"}]
}

Muestre los candidatos a la persona a la que está ayudando y luego vuelva a llamar a la guía con su respuesta, devolviendo el candidato exactamente como se le dio. Cuando no se encuentra el archivo, la respuesta enumera en su lugar los nombres más cercanos e informa de cuántos archivos buscó, de modo que “no está” se pueda distinguir de “no está donde busqué”.

El servidor MCP de PlaidCloud admite dos vías de autenticación:

  1. OAuth 2.1 + PKCE mediante el registro dinámico de clientes (DCR). Es lo que usa la interfaz de conectores personalizados de Claude.ai y también es la opción predeterminada del puente MCP de Claude Code. El cliente se registra por sí mismo y lo redirige al inicio de sesión de Keycloak de PlaidCloud. Después de iniciar sesión, PlaidCloud muestra una página Application Access Request que nombra la aplicación y el URI de redirección al que enviará las credenciales; apruébela una vez por autorización para obtener su token. Es un control de seguridad, no una formalidad: compruebe que el nombre de la aplicación y el URI de redirección coinciden con el cliente al que realmente se está conectando, y no apruebe una solicitud que usted no inició.
  2. Token de portador estático en un encabezado Authorization. Para entornos de ejecución de agentes que no tienen una redirección de navegador utilizable o que quieren un token de larga duración en un archivo de configuración. PlaidCloud expone una página auxiliar para generar uno por usted (consulte más abajo).

Obtención de un token de portador estático

Sección titulada «Obtención de un token de portador estático»

Abra esta URL en una pestaña del navegador donde ya haya iniciado sesión en PlaidCloud:

https://<your-workspace>.plaid.cloud/mcp/setup/token

La página devuelve un fragmento JSON listo para pegar en la configuración MCP de su agente. Cada espacio de trabajo tiene su propio fragmento.

La duración del token se rige por la política de duración del token de acceso de su dominio de Keycloak (normalmente de unas horas a un día). Para actualizarlo, vuelva a cargar la misma URL: la sesión de su navegador vuelve a generar el token automáticamente.

El resto de esta sección explica la configuración para clientes de agentes de IA específicos:

  • Claude Code: el agente de codificación de Anthropic (CLI, extensión de VSCode, complemento de JetBrains).
  • Claude Desktop y Claude.ai: la aplicación Claude para consumidores (escritorio) y la web (claude.ai) mediante los “Custom Connectors”.
  • Cursor: el editor de código nativo de IA.
  • GitHub Copilot: el modo agente de Copilot en VSCode.
  • Google Gemini CLI: gemini-cli y Gemini Code Assist.
  • ChatGPT: estado actual de compatibilidad y solución alternativa recomendada.
  • Grok: conexión de los conectores personalizados de Grok.
  • Solución de problemas: errores habituales y cómo corregirlos.