Conecta Widgetry a tu agente

#La respuesta corta

Para conectar Widgetry a un agente, añade el servidor MCP remoto https://widgets.gonzaloverdugo.com/mcp. Las apps de chat como Claude y ChatGPT conectan con OAuth: añades la URL como conector personalizado, entras con Google y eliges la organización. Los agentes de código como Claude Code, Cursor, VS Code y Codex suelen mandar una clave de API que empieza por wgt_ en la cabecera Authorization: Bearer. En Claude Code basta un comando:

claude mcp add --transport http widgetry https://widgets.gonzaloverdugo.com/mcp \
  --header "Authorization: Bearer $WIDGETRY_API_KEY"

Una vez conectado, el agente recibe las tools widgetry_* (leer, y también construir si la credencial puede escribir) y una tool show_<slug> por cada widget publicado. Qué hace cada tool, con un ejemplo completo, está en Deja que tu agente cree widgets de MCP Apps. Esta guía va de cómo conectarlo, cliente a cliente.

#OAuth o clave de API: cuál usar

Las dos llegan al mismo endpoint y a las mismas tools. Cada credencial pertenece a una organización, y el agente solo ve los widgets y diseños de esa organización.

#OAuth: entras desde el cliente

El cliente te manda a Widgetry. Entras con Google y llegas a una página de consentimiento que dice qué cliente pide acceso, enseña tus organizaciones y te deja Permitir o Cancelar. La organización que marques ahí es la que queda atada al token. La página dice también qué pide el cliente:

• widgets:read: el agente puede leer los widgets y diseños de la organización, borradores incluidos, y pintar los widgets publicados en la conversación. No puede cambiar nada.
• widgets:write: además puede crear, editar, publicar y borrar widgets y diseños.

Tu papel sigue contando. Escribir exige que detrás del token haya un editor o un propietario, así que un lector solo recibe las tools de lectura. Un token sin widgets:write también actúa como lector, aunque seas propietario. Widgetry comprueba en cada petición que sigues siendo miembro: si alguien sale de la organización, su agente pierde el acceso al momento.

#Clave de API: una cabecera que manda el cliente

Las claves las crea un propietario en Ajustes, en el apartado Claves de API: un nombre (por ejemplo, "Agente del portátil") y un permiso, Lectura o Lectura y escritura. La clave se enseña una sola vez, junto con el comando de Claude Code de arriba, así que cópiala antes de pulsar Ya la he guardado. Widgetry solo guarda su hash.

Una clave de lectura le da al agente las tools de lectura y las show_<slug>. Una de lectura y escritura le da todas. El cliente la manda como Authorization: Bearer wgt_....

#Cuándo usar cada una

#Claude: claude.ai y Claude Desktop

Claude añade servidores MCP remotos como conectores personalizados (documentación de Claude, a octubre de 2026). Los nombres de menú van como en la interfaz en inglés:

1. Ve a Customize > Connectors y pulsa Add custom connector.
2. Escribe un nombre, por ejemplo Widgetry, y la URL https://widgets.gonzaloverdugo.com/mcp.
3. Si el diálogo pregunta por Authentication, elige Sign in now. Si pregunta por el OAuth client, elige Register automatically: Widgetry admite el registro dinámico de clientes (Dynamic Client Registration), no la identidad publicada de Claude.
4. Pulsa Add y después Connect. Claude abre Widgetry: entra, elige la organización y pulsa Permitir.

En un plan Team o Enterprise, un Owner añade el conector en Organization settings > Connectors y cada miembro pulsa Connect con su propia cuenta. Dentro de un chat, los conectores se encienden y se apagan desde el botón +, en Connectors.

El OAuth de Widgetry se hizo y se probó con claude.ai y Claude Desktop. Claude pinta MCP Apps en la web, en escritorio y en el móvil, así que show_<slug> dibuja el widget en el chat. Los conectores que añades en la web o en escritorio llegan también a la app del móvil.

#ChatGPT

ChatGPT conecta servidores MCP remotos en modo desarrollador (documentación de OpenAI, a octubre de 2026):

1. Abre Settings, entra en Security and login y activa Developer mode. Que puedas hacerlo depende de tu cuenta y de la política de tu espacio de trabajo.
2. Ve a ChatGPT Plugins, pulsa el botón de más y escribe un nombre y una descripción.
3. En Connection, pon https://widgets.gonzaloverdugo.com/mcp y crea la conexión.

ChatGPT se autentica con OAuth 2.1 y se registra como cliente con Client ID Metadata Documents, con registro dinámico o con un cliente predefinido; no manda claves de API fijas (autenticación en ChatGPT). Widgetry publica los metadatos estándar del recurso protegido y admite el registro dinámico, así que el inicio de sesión debería llevarte a la misma página de consentimiento. El flujo es estándar, pero a octubre de 2026 el OAuth de Widgetry se ha probado con Claude, no con ChatGPT. ChatGPT pinta MCP Apps, así que los widgets se dibujan en el chat.

#Claude Code

Crea una clave en Ajustes, guárdala en una variable de entorno y lanza el comando del principio. Claude Code guarda el servidor en su ámbito local por defecto; añade --scope user para tenerlo en todos los proyectos (documentación de Claude Code).

Si quieres compartir la configuración con el equipo sin compartir la clave, ponla en .mcp.json y que cada persona defina WIDGETRY_API_KEY. Claude Code expande ${VAR} en ese fichero:

{
  "mcpServers": {
    "widgetry": {
      "type": "http",
      "url": "https://widgets.gonzaloverdugo.com/mcp",
      "headers": { "Authorization": "Bearer ${WIDGETRY_API_KEY}" }
    }
  }
}

Claude Code no pinta MCP Apps: llama a show_<slug> y lee el resultado como texto (qué clientes pintan MCP Apps). Aun así, puede crear, editar y publicar widgets con las tools. Para verlos, abre el editorUrl o el previewUrl que te devuelve.

#Cursor

Añade el servidor a .cursor/mcp.json en el proyecto, o a ~/.cursor/mcp.json para todos. Cursor lee variables de entorno con ${env:NOMBRE} (documentación de Cursor):

{
  "mcpServers": {
    "widgetry": {
      "url": "https://widgets.gonzaloverdugo.com/mcp",
      "headers": { "Authorization": "Bearer ${env:WIDGETRY_API_KEY}" }
    }
  }
}

Cursor pinta MCP Apps en el chat del agente desde la versión 2.6.

#VS Code con GitHub Copilot

Pon esto en .vscode/mcp.json, o ejecuta MCP: Open User Configuration para tenerlo en todos los espacios de trabajo. La entrada de inputs hace que VS Code te pida la clave una vez y la guarde, así que el fichero no lleva ningún secreto (documentación de VS Code):

{
  "servers": {
    "widgetry": {
      "type": "http",
      "url": "https://widgets.gonzaloverdugo.com/mcp",
      "headers": { "Authorization": "Bearer ${input:widgetry-key}" }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "widgetry-key",
      "description": "Clave de API de Widgetry",
      "password": true
    }
  ]
}

El chat de GitHub Copilot en VS Code pinta MCP Apps.

#Codex

Codex guarda los servidores MCP en ~/.codex/config.toml, que comparten la CLI de Codex, la extensión del IDE y la app de escritorio de ChatGPT. bearer_token_env_var dice qué variable guarda la clave (documentación de Codex):

[mcp_servers.widgetry]
url = "https://widgets.gonzaloverdugo.com/mcp"
bearer_token_env_var = "WIDGETRY_API_KEY"

Codex también admite OAuth con registro dinámico (codex mcp login widgetry), pero la clave es el camino más corto. Cuenta con que la CLI de Codex solo trabaja con texto: puede construir widgets, no dibujarlos.

#Cualquier otro cliente MCP

Busca en la documentación del cliente "remote MCP server", "Streamable HTTP" o "custom connector". Necesitas dos cosas: la URL https://widgets.gonzaloverdugo.com/mcp y, o bien OAuth (con registro dinámico de clientes), o bien la cabecera Authorization: Bearer wgt_.... Widgetry lee también la clave de una cabecera x-api-key, para los clientes que solo dejan elegir esa.

#Comprueba que funciona

Pídele al agente: "Llama a widgetry_get_organization y dime qué ves". Te contestará algo así (datos inventados):

{
  "organization": { "slug": "estudio-faro", "name": "Estudio Faro" },
  "credential": { "kind": "api-key", "scopes": ["read", "write"], "canWrite": true },
  "widgets": { "total": 4, "published": 2 },
  "designs": { "builtIn": 20, "own": 1 },
  "mcpUrl": "https://widgets.gonzaloverdugo.com/mcp",
  "appUrl": "https://widgets.gonzaloverdugo.com/widgets"
}

Mira tres cosas. Que la organización sea la que querías. Que canWrite sea lo que esperabas: con OAuth, la credencial sale como "kind": "member" con tu papel, y un token de solo lectura sale con el papel viewer. Y que las cifras cuadren con lo que ves en la web. Si el cliente ni siquiera conecta, Widgetry ha respondido 401: la clave está mal copiada, le falta el prefijo Bearer o está revocada, o el inicio de sesión de OAuth no terminó. Corrige la clave, o quita el conector y vuelve a conectarlo.

#Qué pedirle cuando ya está conectado

Algunas peticiones para empezar, y qué hace el agente con cada una:

1. "Enséñame mis widgets publicados." Llama a widgetry_list_widgets y te da nombre, estado y diseño de cada uno.
2. "¿De qué plantillas puedo partir?" widgetry_list_starters devuelve los 13 tipos y las librerías de script.
3. "Enséñame el tablero del sprint con estas tareas: ..." Llama a show_<slug> con tus datos, y un host que pinta MCP Apps lo dibuja.
4. "Crea un widget de donut con el gasto de mi equipo, con el diseño de mi marca, y publícalo." Lee la plantilla de donut, crea el widget, le pone el diseño y los datos de ejemplo, y lo publica.
5. "Haz que el gráfico de barras use nuestras zonas de venta: Norte, Sur, Este y Oeste." Cambia el esquema de datos y los datos de ejemplo con widgetry_update_widget.
6. "Ponle a nuestro diseño un acento para el modo oscuro: un verde azulado más claro." Cambia los tokens oscuros con widgetry_update_design. Más en Crea tu propio diseño.
7. "Hazme un diseño sobre nordic con acento naranja que se llame Brasa." widgetry_create_design crea un diseño que puedes ponerle a cualquier widget.
8. "Dame el código para usar el widget de métricas semanales en mi servidor MCP." widgetry_export_widget devuelve la URL viva y el TypeScript para enlazarlo.
9. "Despublica el widget de la hoja de ruta antigua." widgetry_set_published con false. Su tool desaparece del endpoint.
10. "Abre el widget de cuenta atrás en el editor." Te da el editorUrl; ábrelo con la sesión iniciada.

Los widgets enseñan los datos que les pasa el agente. Si los datos están en otro sitio, dáselos tú o conecta la herramienta que los tiene.

#Para no llevarte sustos

• Una clave es una contraseña. Guárdala en una variable de entorno o en un input que la pida, nunca en un fichero que vayas a commitear ni en un chat.
• Claves de lectura donde no haga falta escribir. Un servidor que solo enlaza widgets publicados necesita una clave de lectura.
• Revoca lo que no uses. En Ajustes, cada clave dice cuándo se usó por última vez, y Revocar la corta al momento.
• Borrar pide confirmación. Las tools de borrar van marcadas como destructivas, y el servidor le dice al agente que te pregunte antes. Un widget borrado no se recupera.
• Miembros y claves se quedan en la web. Ningún agente puede invitar a gente, cambiar papeles ni crear claves, así que ninguna clave acaba escrita en una conversación.

¿Aún no tienes cuenta? Entra con Google y sigue Primeros pasos para publicar tu primer widget.