Integraciones

MCP: configura HelpStack pidiéndolo

HelpStack habla MCP (Model Context Protocol), así que un asistente de IA como Claude puede configurar tu espacio de trabajo por ti. Tú describes lo que quieres con tus palabras; él añade los artículos de la base de conocimiento, los chips de FAQ y las herramientas del agente.

«Rastrea nuestro centro de ayuda y luego añade una herramienta que busque un pedido por su número y correo en https://api.mystore.si/orders.»

Es una conexión de configuración por defecto: configura el espacio de trabajo. Solo lee tus conversaciones o responde a un cliente si un administrador marca esos permisos al crear el token, lo que requiere el plan Growth. El resto de los límites está en Lo que no puede hacer.

Datos rápidos#


Endpoint	`https://helpstack.eu/api/mcp`
Transporte	Streamable HTTP (sin proceso local que instalar)
Autenticación	Un token (`Authorization: Bearer hs_…`) o inicio de sesión en los clientes que lo requieran
Quién puede crear un token	Propietario o administrador
Qué puede hacer un token	Lo que permita tu propio rol, en una organización
Plan	Starter o superior (el indicador `mcp`; dínoslo si estás en Free y lo necesitas)
Límite de peticiones	120 por minuto, por token

1. Crea un token#

Ajustes → Tokens de API → Crear un token. Ponle un nombre que reconozcas más adelante, como «Claude en mi portátil», porque ese nombre es como sabrás cuál revocar.

El token se muestra una sola vez. Solo guardamos su hash, así que no hay pantalla que pueda volver a mostrarlo ni solicitud de soporte que pueda recuperarlo. Si lo pierdes, revócalo y crea otro. Son diez segundos y es el camino previsto, no un fallo.

Un token está ligado a una organización: aquella en la que estabas al crearlo. Si perteneces a varias, crea un token por cada organización que quieras configurar. Un token no puede moverse entre ellas, y unirte más tarde a otra organización no amplía un token que ya tienes.

1b. Elige qué puede hacer el token#

Al crear un token marcas a qué puede acceder. Un token nunca puede hacer más que tú — tu rol sigue aplicándose — y los permisos solo lo restringen más.

Permiso	Qué permite
`settings:read`	Ver canales, herramientas del agente, artículos de la base de conocimiento y FAQ.
`settings:write`	Crear y editar herramientas del agente, artículos y FAQ, y elegir de qué responde un canal. Implica `settings:read`.
`conversations:read`	Leer conversaciones de clientes, incluidos nombres, correos y todo lo que un cliente haya escrito. Plan Growth o superior.
`conversations:draft`	Escribir borradores de respuesta para que los apruebe una persona. No puede enviar. Implica `conversations:read`. Plan Growth o superior.
`conversations:send`	Responder directamente al cliente, sin que nadie lo revise antes. Un mensaje enviado no se puede recuperar. Implica `conversations:read`, y `conversations:draft` nunca lo implica. Plan Growth o superior.
`analytics:read`	Ver cifras agregadas: volumen, tiempos de respuesta y resolución, desgloses por etiqueta y sentimiento, rendimiento de la IA y gasto. Solo números: no puede leer lo que escribió ningún cliente. No implica nada y nada lo implica. Plan Growth o superior.

Los dos permisos settings: vienen marcados por defecto: es la superficie de configuración que describe esta página. Los dos permisos conversations: nunca vienen marcados — mostrarle tu bandeja a un asistente debería ser una decisión que alguien toma, no una que hereda — y solo aparecen a partir del plan Growth. Desmarca settings:write y obtienes un token que puede mirar tu configuración y no cambiar nada, útil para que un asistente audite un montaje o responda a «¿qué tenemos configurado realmente?» sin ningún riesgo de que edite.

tools/list solo muestra las herramientas que el token puede invocar, así que un asistente nunca ve una puerta que no puede abrir.

2. Conecta tu asistente#

Claude Code:

claude mcp add helpstack --transport http https://helpstack.eu/api/mcp \
  --header "Authorization: Bearer hs_your_token_here"

Claude Desktop y ChatGPT — añade un conector personalizado apuntando a https://helpstack.eu/api/mcp e inicia sesión cuando te lo pida. Estos clientes no pueden enviar un token que pegues, así que usan un inicio de sesión: eliges qué organización conectar y apruebas lo que la aplicación puede hacer, en una página de HelpStack. No se concede nada hasta que lo apruebas, y luego puedes desconectar la aplicación desde Ajustes → Tokens de API.

Para esa vía no necesitas crear un token. Los tokens son para clientes como Claude Code, que pueden poner la cabecera ellos mismos.

Codex — lee el token de una variable de entorno, así que nunca acaba en tu archivo de configuración:

export HELPSTACK_MCP_TOKEN="hs_tu_token"
codex mcp add helpstack --url https://helpstack.eu/api/mcp \
  --bearer-token-env-var HELPSTACK_MCP_TOKEN

Cualquier otra cosa que hable MCP sobre HTTP — apúntala a la misma URL con la misma cabecera. No hay nada específico de HelpStack en el transporte.

Después pídele que ejecute whoami. Debería responder con el nombre de tu organización y tu rol. Si lo hace, todo lo de abajo funcionará.

Dos formas de conectar#

	Token	Inicio de sesión
Para quién	Claude Code, scripts, cualquier cosa que pueda poner una cabecera	Claude Desktop, ChatGPT, interfaces de conectores
Cómo se configura	Creas un token aquí y lo pegas una vez	Añades la URL y apruebas en una página de HelpStack
Elegir organización	Fijada al crear el token	Elegida al aprobar
Cómo se desactiva	Revocas el token	Desconectas la aplicación

Ambas acaban igual: una identidad con un rol, una organización y un conjunto de permisos, comprobados en cada llamada.

Lo que puede hacer#

Herramienta	Qué hace
`whoami`	Para qué organización actúa el token, y con qué rol
`list_channels`	Tus canales, con sus ids y tipos
`create_channel`	Añadir un canal de chat web, si quieres copiando el aspecto del widget de otro canal. Los canales de correo, redes sociales y voz necesitan un inicio de sesión y siguen siendo cosa del panel
`get_channel_settings`	Cómo se comporta un canal: activo o no, si la IA responde y si esas respuestas salen sin revisión, traducción e idiomas, y de dónde responde
`update_channel_settings`	Cambiar cualquiera de esas cosas: activar las respuestas de la IA, dejarlas como borrador, fijar el idioma del equipo, renombrar o apagar el canal
`list_agent_tools`	Las herramientas que la IA ya puede invocar, incluidas las integradas
`create_agent_tool`	Añade una herramienta para que la IA llame a tu API al responder, ejecute código en la página del visitante (`CLIENT_SIDE`) u ofrezca un botón «Muéstramelo» (`CLIENT_ACTION`). Plan Growth o superior
`update_agent_tool`	Cambia la descripción, URL, parámetros o estado activo de una herramienta, o la cambia entre `CLIENT_SIDE` y `CLIENT_ACTION`
`delete_agent_tool`	Elimina una herramienta que hayas creado
`get_agent_tool_logs`	Llamadas recientes a una herramienta: el primer sitio donde mirar si falla. Los botones registran `OFFERED`, `TAPPED` y luego `SUCCESS` o `FAILED`
`list_knowledge_base_sources`	Los sitios que se están rastreando, y su estado
`add_knowledge_base_url`	Rastrea un sitio hacia la base de conocimiento
`recrawl_knowledge_base_source`	Vuelve a ejecutar un rastreo, llegando más lejos que la vez anterior
`delete_knowledge_base_source`	Elimina un sitio rastreado y sus artículos
`list_knowledge_base_articles`	Todos los artículos, con origen y estado
`add_knowledge_base_article`	Escribe un artículo a mano
`update_knowledge_base_article`	Edita un artículo escrito a mano
`delete_knowledge_base_article`	Elimina un artículo
`list_knowledge_base_groups`	Grupos, con recuento de artículos y canales
`create_knowledge_base_group`	Agrupa artículos relacionados para poder dirigirlos
`attach_knowledge_base_groups_to_channel`	Elige de qué responde un canal
`get_widget_config`	Los ajustes del widget de un canal de chat web: color, posición, saludo, reglas proactivas, horario y dominios permitidos
`update_widget_config`	Cambia cualquiera de ellos. Los crea si el canal no los tiene, que es lo que hace que el widget aparezca
`list_tags`	Tu taxonomía de etiquetas: las de tema registran de qué iba una conversación, las de estado la describen ahora mismo. Plan Growth o superior
`create_tag`	Añadir una etiqueta. Su tipo queda fijado al crearla, porque cambiarlo reescribiría lo que significó cada uso anterior
`update_tag`	Renombrar una etiqueta o cambiar su descripción, color o categoría
`archive_tag`	Retirar una etiqueta de uso. Las conversaciones ya etiquetadas la conservan, y por eso esto no es un borrado
`restore_tag`	Recuperar una etiqueta archivada con el nombre que sigue ocupando
`list_tag_categories`	Los grupos en los que se organizan las etiquetas, y cuáles son exclusivos
`create_tag_category`	Agrupar etiquetas — "Sentimiento", "Estado", "Área de producto". Una categoría exclusiva solo admite una etiqueta a la vez
`update_tag_category`	Renombrar una categoría, reordenarla o cambiar si es exclusiva
`archive_tag_category`	Dejar de usar una agrupación. Sus etiquetas siguen existiendo, sin grupo
`list_team_members`	Quién está en la organización, con su rol — de aquí salen los ids de agente para una regla de enrutado
`list_assignment_rules`	Tus reglas de enrutado, en el orden en que se evalúan
`create_assignment_rule`	Repartir las conversaciones nuevas de un canal entre un grupo de agentes, por turnos. Con `tagIds` opcionales (ids de `list_tags`, requiere el etiquetado de conversaciones en tu plan) la regla enruta en cambio una conversación en cuanto tiene alguna de esas etiquetas, nunca por encima de una asignación manual; las etiquetas de la categoría Sentiment se rechazan. Sin `order`, la regla se añade al final
`update_assignment_rule`	Cambiar las condiciones, el grupo, el orden o si la regla está activa. Se rechaza quitar la última condición de una regla que tenía alguna
`delete_assignment_rule`	Eliminar una regla. Las conversaciones que ya asignó conservan su responsable
`update_organization`	Fijar el nombre del negocio que ven los clientes y el idioma por defecto que heredan los canales nuevos
`get_notification_preferences`	Qué notificaciones recibe el miembro propietario del token
`set_notification_preferences`	Cambiarlas — para esa persona, nunca para el equipo
`list_faqs`	Los chips de FAQ de la pantalla de bienvenida del widget
`create_faq`	Añade un chip de FAQ
`update_faq`	Cambia la pregunta, la respuesta o la visibilidad de un chip
`delete_faq`	Elimina un chip
`list_conversations`	Conversaciones de clientes, las más recientes primero, filtrables por estado y canal
`get_conversation`	Una conversación completa, todos los mensajes en orden
`draft_reply`	Escribe un borrador en la bandeja para que una persona lo apruebe y envíe
`send_reply`	Responde directamente al cliente, sin revisión
`get_data_coverage`	Cuándo empieza cada conjunto de datos, para no comparar nunca contra datos que no existen
`get_analytics`	Volumen, tiempos de respuesta y resolución, IA frente a humano, horas punta, canales, agentes, resultados de borradores, gasto y etiquetas incluido el sentimiento
`search_conversations`	Cuenta las conversaciones que mencionan una palabra, con extractos cortos. Necesita `conversations:read`, no `analytics:read`, porque devuelve lo que escribieron los clientes

Lo que tu asistente sabe antes de llamar

Cada herramienta se publica con tres indicaciones: si solo lee, si su efecto se puede deshacer y qué permiso necesita. Clientes como Claude, Cursor y ChatGPT las usan para decidir qué ponerte delante primero, así que listar tus canales pasa sin ruido mientras enviar una respuesta pregunta.

Dos de ellas merecen conocerse:

Solo dos herramientas salen de HelpStack. add_knowledge_base_url y recrawl_knowledge_base_source descargan una página de la web. Cualquier otra se queda dentro de tu propio espacio de trabajo.
send_reply está marcada como irreversible, igual que las cuatro herramientas de borrado y las ediciones que sobrescriben algo en su sitio. draft_reply no lo está: un borrador que nadie ha aprobado no ha llegado a nadie, así que retirarlo no cuesta nada.

Las indicaciones son un consejo para el cliente, no un candado. Lo que un token puede hacer de verdad lo siguen decidiendo sus permisos y tu rol, comprobados en cada llamada.

Números sin la bandeja de entrada

analytics:read y conversations:read están separados a propósito, y esa es la distinción que conviene entender antes de marcar nada. get_analytics devuelve agregados: cuántas conversaciones, con qué rapidez se respondieron, qué etiquetas crecen, en qué se equivocó la IA. Nada de eso es algo que escribiera un cliente. search_conversations devuelve texto de clientes, así que va con las herramientas de la bandeja.

Así puedes dar tus números a un asistente sin darle tu bandeja de entrada. «Los reembolsos han subido un 40 %» y «esto es lo que dijeron catorce personas sobre reembolsos» son revelaciones distintas y se conceden por separado.

Leer está disponible para cualquier miembro. Escribir requiere propietario o administrador, igual que en el panel: el token de un agente puede mirar, pero no cambiar nada. Eso se comprueba antes que tus argumentos, así que un token sin permiso no averigua nada sobre una herramienta al invocarla.

La pieza que lo une todo

attach_knowledge_base_groups_to_channel es el paso que se olvida. Añadir artículos no los dirige a ninguna parte: un canal sin grupos asignados busca en toda tu base de conocimiento, lo cual está bien para un tema y mal para varios. Agrupa los artículos, asigna el grupo, y la IA responderá en ese canal desde esa porción.

Responder a las difíciles#

Con conversations:read y conversations:draft, un asistente puede leer un hilo complicado y escribirte una respuesta meditada:

Tú: Lee la conversación 4821 y redacta una respuesta. El cliente tiene razón en que enviamos tarde, pero el reembolso que pide es mayor que el pedido.

Llama a get_conversation, lee el hilo entero y llama a draft_reply. El borrador aparece en tu bandeja igual que uno generado por la IA, y lo envías tú.

Un borrador no llega al cliente. draft_reply nunca encola un envío: el borrador queda inerte hasta que una persona lo aprueba en HelpStack, donde la aprobación queda registrada a su nombre.

En un canal de correo con plantilla de respuesta, escriba solo el cuerpo. El saludo y la despedida (línea de cierre y firmante) se añaden al enviar el correo, así que draft_reply y send_reply quitan el saludo o la despedida que haya escrito su asistente en lugar de enviarlos dos veces.

Enviar es un permiso aparte, conversations:send, y esa separación es la clave. conversations:draft no lo implica, nada más lo concede y nunca viene marcado. «Escríbeme una respuesta» y «respóndeles por mí» son decisiones distintas, así que son permisos distintos.

Si lo concedes, send_reply responde de inmediato y sin revisión, igual que ya hacen tus canales con la respuesta automática activada. Ejecuta la misma detección de idioma y traducción que el botón de aprobar, para que una respuesta en inglés no llegue a un cliente que escribió en esloveno, y el mensaje se atribuye a la persona dueña del token en lugar de a un asistente anónimo. Un mensaje enviado no se puede recuperar.

Los borradores sin enviar se marcan cuando el asistente vuelve a leer el hilo, para que nunca confunda su propio borrador con algo que el cliente ya ha visto.

Lo que no puede hacer#

Deliberadamente, y esta es la mitad más útil de la lista:

No puede enviar salvo que concedas conversations:send, que está desactivado por defecto, es independiente de redactar y solo está en Growth.
No ve otra organización. La organización sale del token y nunca es algo que pase quien llama.
No puede leer tu bandeja salvo que lo concedas. Los permisos de conversaciones están desactivados hasta que los marques, y no están disponibles por debajo del plan Growth.
No puede exceder tus propios permisos. Un token actúa como la persona que lo creó, con el rol que tiene ahora.
No sobrevive a tu pertenencia. Quita a alguien de la organización y sus tokens dejan de funcionar en la siguiente llamada.
No toca las credenciales de un canal. Las contraseñas de buzón, los refresh tokens de Google y los tokens de página de Meta no son un campo en ninguna herramienta, así que conectar un canal sigue siendo cosa del panel. Puede cambiar cómo se comporta un canal, no con qué se identifica.
No puede crear un token. Un token capaz de emitir tokens escaparía de sus propios permisos en una sola llamada, así que no existe la herramienta. Los tokens los crea una persona en los ajustes.
No puede añadir ni quitar miembros, ni cambiar roles. Cambiar quién llega a tu bandeja es la misma escalada que emitir un token: list_team_members lee y nada escribe. Las invitaciones siguen en el panel.
No toca la facturación. Ninguna herramienta inicia un pago, cambia de plan ni abre el portal de facturación.
No puede conectar Shopify ni WooCommerce. Ambos necesitan una persona en un navegador: una pantalla de OAuth, o un código de emparejamiento pegado en WordPress.
No cambia las notificaciones de nadie más. Una preferencia pertenece a una persona, así que set_notification_preferences escribe las del propietario del token y las de nadie más.
No cambia el slug de la organización. Tu nombre y tu idioma por defecto se pueden cambiar; el slug aparece en los enlaces y no.
No conserva un permiso que tu plan haya perdido. Si bajas de Growth, los permisos de conversaciones dejan de funcionar ese mismo día, incluso en tokens ya emitidos. Con las etiquetas pasa lo mismo: las herramientas de taxonomía rechazan a una organización por debajo de Growth, así que MCP nunca es una forma de sortear el plan.

Ejemplo#

Montar el soporte de una tienda desde cero, en una sola conversación:

Tú: Este es nuestro centro de ayuda: https://mystore.si/pomoc. Rastréalo, luego añade un chip de FAQ sobre plazos de entrega y una herramienta que consulte el estado del pedido en nuestra API.

El asistente llamará a add_knowledge_base_url, luego a create_faq y luego a create_agent_tool — y normalmente llamará antes a list_agent_tools para no duplicar una herramienta que ya tienes.

Dos cosas que esperar:

El rastreo no es instantáneo. Cada ejecución indexa unas 50 páginas y volver a ejecutarlo llega más lejos, así que un sitio grande se cubre en varios rastreos. Pide list_knowledge_base_sources para ver por dónde va.
La descripción de una herramienta es lo importante. Es lo que el modelo lee para decidir cuándo llamarla. Dilo en términos llanos — «úsala solo cuando el cliente dé tanto el número de pedido como el correo con el que compró» — y quedará escrito en la descripción, que es su sitio.

Cuando algo se rechaza#

Los errores que más probablemente verás, y qué significan:

Mensaje	Qué ha pasado
`unauthorized`	El token es incorrecto, está revocado, o su propietario ha salido de la organización. Crea uno nuevo.
`This token belongs to a member who cannot change settings.`	El propietario del token es agente o visor. Escribir requiere propietario o administrador.
`Custom agent tools are available on the Growth plan and up.`	Exactamente eso. Leer herramientas sigue funcionando.
`Website limit for your plan reached.`	Elimina una fuente de la base de conocimiento o mejora el plan.
`invalid arguments: …`	El asistente envió un campo que no aceptamos. Los campos desconocidos se rechazan en vez de ignorarse, para que una errata falle de forma visible en lugar de hacer otra cosa en silencio.

Cómo mantener seguro un token#

Un token es una contraseña que se teclea sola. Trátalo como tal:

Un token por sitio donde se use, para que revocar uno no rompa los demás.
Revócalo cuando dejes de usarlo. Ajustes → Tokens de API muestra cuándo se usó cada uno por última vez, lo que suele bastar para saber cuál está inactivo.
No lo pegues en un documento compartido ni en un chat. Si lo has hecho, revócalo: el coste de equivocarse es que alguien reconfigure tu asistente.
No es para tus clientes ni para tu web. Va en máquinas que tú controlas.

Relacionado#

Herramientas del agente — qué son y cómo escribir una buena descripción.
Herramientas del agente personalizadas — la referencia del integrador para los endpoints que llaman tus herramientas.
Base de conocimiento — cómo se comportan el rastreo y los artículos.
Indicadores de funciones — qué capacidades incluye tu plan.

Editar esta página en GitHub