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, no de soporte. Configura el espacio de trabajo. No puede leer tus conversaciones ni responder a un cliente — consulta Lo que no puede hacer.

Datos rápidos#

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.

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#

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

Lo que puede hacer#

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.

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 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.

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:

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.