Ethora MCP CLI
SDK
Documentación
Servidor Ethora MCP (Model Context Protocol)
Instalación con un clic para Cursor y VS Code (botones arriba). Para Claude Code, Claude Desktop, GitHub Copilot, Gemini CLI, Codex CLI, Windsurf y Cline, consulta Uso con clientes MCP más abajo.
Un CLI/servidor MCP (Model Context Protocol) que conecta clientes MCP populares a la plataforma Ethora — una plataforma de chat y mensajería de código abierto con un framework integrado de agentes de IA / chatbots. Se ejecuta localmente en la máquina de un desarrollador mediante stdio, no como un servicio Ethora alojado.
Úsalo desde Cursor, VS Code MCP, Claude Desktop o Windsurf/Cline para gestionar aplicaciones y salas de chat, difundir mensajes, implementar agentes de IA / chatbots con fuentes RAG y automatizar flujos de aprovisionamiento B2B. (También se incluyen herramientas de wallet ERC-20 — consulta la lista de herramientas más abajo).
Parte del ecosistema del SDK de Ethora — consulta todos los SDK, herramientas y aplicaciones de ejemplo. Sigue las actualizaciones entre SDK en las Notas de versión.
- npm: https://www.npmjs.com/package/@ethora/mcp-server
- API Ethora predeterminada:
https://api.chat.ethora.com/v1(Swagger: https://api.chat.ethora.com/api-docs/#/)
✨ Qué obtienes
- Habla con la plataforma Ethora directamente desde tu IDE o cliente de agente de IA (Cursor, VS Code MCP, Claude Desktop, Windsurf / Cline).
- Tanto flujos de autenticación de usuario (inicio de sesión/registro, archivos, endpoints de propietario/admin) como flujos B2B / token de aplicación (aprovisionamiento de inquilinos, trabajos de difusión, lotes de usuarios asíncronos, configuración de bots de IA).
- Recetas, prompts y generadores integrados para los flujos de trabajo de Ethora más comunes (configuración de componentes de chat Vite/Next, arranque B2B, habilitación de bots de IA, fuentes RAG).
- Envoltura de respuesta de herramienta estándar (
{ ok, ts, meta, data | error }) para que el código del agente pueda razonar sobre éxito/fallo de manera consistente.
🚦 ¿Solo probándolo? (inicio rápido de 60 segundos)
No leas aún los modos de autenticación. Una vez que el servidor esté conectado en tu cliente, pide a tu agente que ejecute, en orden:
ethora-doctor— confirma que el servidor está activo y puede alcanzar la API de Ethora. No se necesitan credenciales.ethora-configurecon tuappJwt→ethora-auth-use-user→ethora-user-logincon un correo electrónico y una contraseña.ethora-app-list— ya estás dentro; esto lista tus aplicaciones.
Ese es el camino del desarrollador local. ¿Necesitas automatización del lado del servidor? Salta al modo B2B. ¿Perdido en algún punto? Llama a ethora-help — lee tu estado actual y te indica la siguiente llamada.
🔐 Dos modos de uso típicos
1) Modo de autenticación de usuario
Ideal para:
- desarrolladores que prueban Ethora localmente
- administradores de inquilinos / propietarios de aplicaciones que usan MCP manualmente
- flujos que comienzan con
ethora-user-login
Cómo funciona:
- configura
ETHORA_APP_JWTuna vez para el arranque de inicio de sesión/registro - cambia a
ethora-auth-use-user - llama a
ethora-user-login - usa herramientas de autenticación de usuario como archivos y endpoints heredados de propietario/admin
2) Modo B2B
Ideal para:
- integraciones backend permanentes
- flujos de aprovisionamiento de socios
- agentes autónomos que operan Ethora sin una sesión de usuario humano
Cómo funciona:
- configura
ETHORA_B2B_TOKEN - cambia a
ethora-auth-use-b2bpara rutas explícitas de actor de inquilino/v2/apps/:appId/... - opcionalmente cambia a
ethora-auth-use-appdespués deethora-app-selectcuando quieras rutas de conveniencia con ámbito de aplicación impulsadas porappToken
Regla general:
- el primer uso local suele comenzar con autenticación de usuario
- la automatización repetible suele comenzar con B2B y luego a menudo pasa al modo token de aplicación para una aplicación seleccionada
Prompts y recursos (P2: documentación orientada a desarrolladores)
- Recursos (documentos cargables en el contexto)
ethora://docs/auth-map— appJwt vs appToken vs b2bTokenethora://docs/chat-component/quickstart— inicio rápido de Vite/Next + reemplazo de tokens de demostraciónethora://docs/sdk-backend/quickstart— inicio rápido de integración backendethora://docs/recipes— secuencias de herramientas comunes (difusión/fuentes/archivos/bot)
- Prompts
ethora-auth-mapethora-vite-quickstartethora-nextjs-quickstartethora-backend-sdk-quickstartethora-recipes
Generadores (sin shell, sin escritura de archivos)
ethora-generate-chat-component-app-tsx— fragmentoApp.tsxlisto para pegar para@ethora/chat-componentethora-generate-env-examples— plantillas.env.examplepara:- componente de chat frontend
- integración de SDK backend
- uso de MCP (
ETHORA_API_URL,ETHORA_APP_JWT,ETHORA_B2B_TOKEN)
ethora-generate-b2b-bootstrap-runbook— manual mínimo de "llama a estas herramientas MCP en orden" para el arranque B2B
Consejo: para listar recetas ejecutables sin llamar a ethora-help, llama a ethora-run-recipe con goal: "auto" y omite recipeId.
-
Sesión / Configuración
ethora-configure— establece la URL de la API más el App JWT / token B2B / appToken para esta sesión MCPethora-status— muestra la URL de la API configurada, el modo de autenticación activo y qué credenciales están presentesethora-help— ayuda orientada a tareas (próximas llamadas recomendadas + "recetas de un clic" según el estado actual)ethora-run-recipe— ejecuta una receta integrada por id (pasos secuenciales; sin shell, sin escritura de archivos)ethora-doctor— valida la configuración + haz ping a la API de Ethora configurada tanto para uso de usuario como B2Bethora-app-select— selecciona el appId actual y opcionalmente establece appTokenethora-auth-use-app— cambia al modo de autenticación de token de aplicación para operaciones con ámbito de aplicaciónethora-auth-use-user— cambia al modo de autenticación de sesión de usuarioethora-auth-use-b2b— cambia al modo de autenticación B2B de actor de inquilinox-custom-token
-
Chats (v2)
ethora-chats-broadcast-v2— pone en cola un trabajo de difusión usando autenticación de token de aplicación o B2B +appIdexplícitoethora-chats-broadcast-job-v2— obtiene el estado/resultados del trabajo de difusión usando autenticación de token de aplicación o B2B +appIdexplícitoethora-wait-broadcast-job-v2— consulta el trabajo de difusión hasta que se complete/falla usando autenticación de token de aplicación o B2B +appIdexplícitoethora-chats-message-v2— envía un mensaje de prueba/automatización a través de la superficie de chat de la aplicación (requiere autenticación de token de aplicación)ethora-chats-history-v2— lee el historial persistido de automatización/pruebas para sesiones privadas o de grupo (requiere autenticación de token de aplicación)
-
Usuarios (lote asíncrono v2)
ethora-users-batch-create-v2— crea un trabajo de lote de usuarios asíncrono (requiere autenticación B2B)ethora-users-batch-job-v2— obtiene el estado/resultados del trabajo de lote de usuarios (requiere autenticación B2B)ethora-wait-users-batch-job-v2— consulta el trabajo de lote de usuarios hasta que se complete/falla (requiere autenticación B2B)
-
Archivos (v2)
-
Bot / Agente (v2)
-
ethora-bot-get-v2— obtiene el estado/configuración del bot usando autenticación de token de aplicación o B2B +appIdexplícito -
ethora-bot-update-v2— actualiza la configuración del bot usando autenticación de token de aplicación o B2B +appIdexplícito -
ethora-bot-enable-v2— habilita el bot usando autenticación de token de aplicación o B2B +appIdexplícito -
ethora-bot-disable-v2— deshabilita el bot usando autenticación de token de aplicación o B2B +appIdexplícito -
ethora-bot-widget-v2— obtiene la configuración del widget/embed y los metadatos de la URL pública del widget (autenticación de token de aplicación) -
ethora-agents-list-v2— lista agentes guardados reutilizables para el propietario de la aplicación actual (autenticación de token de aplicación) -
ethora-agents-get-v2— obtiene un agente guardado reutilizable (autenticación de token de aplicación) -
ethora-agents-create-v2— crea un agente guardado reutilizable (autenticación de token de aplicación) -
ethora-agents-update-v2— actualiza un agente guardado reutilizable (autenticación de token de aplicación) -
ethora-agents-clone-v2— clona un agente guardado reutilizable (autenticación de token de aplicación) -
ethora-agents-activate-v2— vincula un agente guardado como el bot activo para la aplicación seleccionada (autenticación de token de aplicación) -
ethora-bot-message-v2— alias de compatibilidad paraethora-chats-message-v2 -
ethora-bot-history-v2— alias de compatibilidad paraethora-chats-history-v2 -
ethora-files-upload-v2— sube archivos (requiere autenticación de usuario) -
ethora-files-get-v2— lista/obtiene archivos (requiere autenticación de usuario) -
ethora-files-delete-v2— elimina archivo por id (requiere autenticación de usuario)
-
-
Fuentes
ethora-sources-site-crawl— rastrea una URL (requiere autenticación de usuario)ethora-sources-site-reindex— reindexa URL por urlId (requiere autenticación de usuario)ethora-sources-site-delete-url— elimina por URL (requiere autenticación de usuario)ethora-sources-site-delete-url-v2— elimina URLs en lote (requiere autenticación de usuario)ethora-sources-docs-upload— sube documentos para ingesta (requiere autenticación de usuario)ethora-sources-docs-delete— elimina documento ingerido por id (requiere autenticación de usuario)ethora-sources-site-crawl-v2— rastrea una URL usando autenticación de token de aplicación o B2B +appIdexplícitoethora-sources-site-reindex-v2— reindexa URL por urlId usando autenticación de token de aplicación o B2B +appIdexplícitoethora-sources-site-crawl-v2-wait— helper de una sola llamada con tiempo de espera largo para rastreo (autenticación de token de aplicación)ethora-sources-site-reindex-v2-wait— helper de una sola llamada con tiempo de espera largo para reindexación (autenticación de token de aplicación)ethora-sources-site-list-v2— lista fuentes de sitios rastreados y etiquetas actuales usando autenticación de token de aplicación o B2B +appIdexplícitoethora-sources-site-tags-update-v2— establece/actualiza etiquetas para una fuente de sitio rastreada usando autenticación de token de aplicación o B2B +appIdexplícitoethora-sources-site-delete-url-v2— elimina una URL rastreada por URL usando autenticación de token de aplicación o B2B +appIdexplícitoethora-sources-site-delete-url-v2-batch— elimina registros de fuentes rastreadas en lote por id usando autenticación de token de aplicación o B2B +appIdexplícitoethora-sources-docs-upload-v2— sube documentos para ingesta usando autenticación de token de aplicación o B2B +appIdexplícitoethora-sources-docs-list-v2— lista documentos indexados y etiquetas actuales usando autenticación de token de aplicación o B2B +appIdexplícitoethora-sources-docs-tags-update-v2— establece/actualiza etiquetas para un documento indexado usando autenticación de token de aplicación o B2B +appIdexplícitoethora-sources-docs-delete-v2— elimina documento por id usando autenticación de token de aplicación o B2B +appIdexplícito
-
Autenticación y cuentas
ethora-user-login— inicia sesión de usuario (correo electrónico + contraseña)ethora-user-register— registra usuario (correo electrónico + nombre/apellido)
-
Aplicaciones
ethora-app-create— crea aplicaciónethora-app-update— actualiza aplicaciónethora-app-delete— elimina aplicaciónethora-app-list— lista aplicacionesethora-b2b-app-create— crea aplicación usando autenticación B2B (x-custom-token)ethora-b2b-app-bootstrap-ai— crea aplicación → indexa fuentes → configura/habilita bot, incluida la selección de LLM en tiempo de ejecución (automatización B2B)ethora-app-tokens-list-v2— lista metadatos de token de aplicación (autenticación B2B)ethora-app-tokens-create-v2— crea nuevo token de aplicación (se devuelve una vez) (autenticación B2B)ethora-app-tokens-rotate-v2— rota token (revoca el antiguo, devuelve el nuevo una vez) (autenticación B2B)ethora-app-tokens-revoke-v2— revoca token por tokenId (idempotente) (autenticación B2B)ethora-b2b-app-provision— crea aplicación + crea tokens + aprovisiona salas + configura bot, incluida la selección de LLM en tiempo de ejecución (orquestador B2B)
-
Chat y salas
ethora-app-get-default-rooms— lista salas predeterminadasethora-app-get-default-rooms-with-app-id— salas para una aplicación dadaethora-app-create-chat— crea chat para aplicaciónethora-app-delete-chat— elimina chat
-
Wallet
ethora-wallet-get-balance— obtiene saldoethora-wallet-erc20-transfer— envía tokens ERC-20
Los nombres de herramientas anteriores reflejan las áreas funcionales expuestas por el servidor. Tus nombres exactos de herramientas pueden variar ligeramente según la versión; ejecuta "list tools" del cliente para confirmar.
📦 Instalación / Ejecución
Requisitos previos
Antes de comenzar, asegúrate de tener lo siguiente:
- Node.js instalado en tu sistema (versión recomendada 18.x o superior).
Instalación
El servidor se distribuye como un paquete npm y normalmente lo lanzan los clientes MCP mediante npx:
npx -y @ethora/mcp-server
No se requiere instalación global.
🔐 Configuración (variables de entorno)
Este servidor MCP admite tanto el flujo local de autenticación de usuario como el flujo B2B del lado del servidor.
Valores principales:
- URL de la API de Ethora (dónde enviar las solicitudes)
- App JWT de Ethora (se usa solo para el arranque de inicio de sesión/registro en el modo de autenticación de usuario)
- Token B2B de Ethora (se usa para flujos servidor a servidor de actor de inquilino)
Puedes proporcionarlos:
- mediante variables de entorno, o
- en tiempo de ejecución mediante la herramienta
ethora-configure(en memoria; se restablece cuando se reinicia el proceso MCP)
Variables de entorno admitidas
ETHORA_API_URL: URL completa de la API (ejemplo:https://api.chat.ethora.com/v1,http://localhost:8080/v1)ETHORA_BASE_URL: URL base del host (ejemplo:https://api.chat.ethora.com,http://localhost:8080)
Si se proporciona, el servidor usará.../v1por defecto.ETHORA_APP_JWT: cadena JWT de la app, normalmente comienza conJWT ...ETHORA_B2B_TOKEN: token de servidor B2B para autenticaciónx-custom-token(JWT contype=server)ETHORA_MCP_ENABLE_DANGEROUS_TOOLS: habilita herramientas destructivas (por defecto: deshabilitadas). Establécelo entruepara exponer:- herramientas de eliminación de apps
- herramientas de transferencia de wallets
- herramientas de borrado masivo
Seguridad: nunca subas JWTs de apps, tokens B2B o appTokens a git. Configúralos mediante variables de entorno, el almacén de secretos del cliente MCP o tu propio backend.
🧱 Envoltura de respuesta estándar (herramientas)
Todas las herramientas devuelven JSON en una envoltura consistente:
- Éxito:
{ ok: true, ts, meta, data } - Error:
{ ok: false, ts, meta, error }, dondeerrorincluye:code: cadena estable (prefiere APIcode, si no, se infiere)httpStatus: estado HTTP cuando el fallo provino de una llamada a la APIrequestId: id de solicitud/correlación si lo devuelve la APIhint: línea de "qué hacer a continuación"
🚀 Uso con clientes MCP
Cada cliente ejecuta lo mismo — npx -y @ethora/mcp-server sobre stdio. Existen botones de un clic para Cursor y VS Code (arriba de este README). Para el resto es un bloque de configuración corto o un comando de una línea.
Cursor
Usa el botón Add to Cursor de arriba, o manualmente: Settings → MCP → Add new global MCP server:
{
"mcpServers": {
"ethora": {
"command": "npx",
"args": ["-y", "@ethora/mcp-server"]
}
}
}
VS Code (y GitHub Copilot)
Usa el botón Install in VS Code de arriba, o añade un archivo .vscode/mcp.json (a nivel de proyecto) — nota que la clave es servers:
{
"servers": {
"ethora": {
"command": "npx",
"args": ["-y", "@ethora/mcp-server"]
}
}
}
El modo agente de GitHub Copilot en VS Code lee este mismo .vscode/mcp.json — no requiere configuración adicional. (Para una instalación a nivel de usuario, coloca el bloque servers bajo "mcp" en tu JSON de User Settings.)
Claude Code
Un comando:
claude mcp add ethora -- npx -y @ethora/mcp-server
Añade --scope user para que esté disponible en todos los proyectos. Verifica con claude mcp list.
Para preconfigurar credenciales, pásalas como variables de entorno con -e (recomendado sobre la herramienta ethora-configure — ver nota abajo):
claude mcp add ethora \
-e ETHORA_API_URL=https://api.chat.ethora.com/v1 \
-e ETHORA_B2B_TOKEN=<your-b2b-token> \
-- npx -y @ethora/mcp-server
Nota sobre secretos: prefiere variables de entorno (arriba) o el almacén de secretos de tu cliente MCP para las credenciales. La herramienta
ethora-configuretambién funciona, pero pasa los secretos como argumentos de herramienta, lo que significa que terminan en la transcripción de la conversación. Úsala para pruebas locales rápidas, no para tokens que te importen.
Claude Desktop
Settings → Developer → Edit Config, abre claude_desktop_config.json:
{
"mcpServers": {
"ethora": {
"command": "npx",
"args": ["-y", "@ethora/mcp-server"]
}
}
}
Gemini CLI
Añade a ~/.gemini/settings.json (global) o .gemini/settings.json (por proyecto):
{
"mcpServers": {
"ethora": {
"command": "npx",
"args": ["-y", "@ethora/mcp-server"]
}
}
}
Codex CLI
Añade a ~/.codex/config.toml — nota que el nombre de la tabla es mcp_servers (con guion bajo; mcp-servers se ignora silenciosamente):
[mcp_servers.ethora]
command = "npx"
args = ["-y", "@ethora/mcp-server"]
Windsurf
Settings → Cascade → MCP Servers → View raw config (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"ethora": {
"command": "npx",
"args": ["-y", "@ethora/mcp-server"]
}
}
}
Cline
Abre el panel de servidores MCP y edita cline_mcp_settings.json:
{
"mcpServers": {
"ethora": {
"command": "npx",
"args": ["-y", "@ethora/mcp-server"]
}
}
}
🧪 Prueba rápida
Después de que el servidor aparezca como conectado en tu cliente:
- Ejecuta
list tools(comando del cliente) para verificar que las herramientas de Ethora están disponibles. - Verifica configuración/conectividad: llama a
ethora-doctor(oethora-status) - Para una primera prueba local/manual:
- llama a
ethora-configureconapiUrl/appJwt - llama a
ethora-auth-use-user - llama a
ethora-user-login - luego prueba
ethora-app-listoethora-wallet-get-balance
- llama a
- Para una prueba del lado del servidor/B2B:
- llama a
ethora-configureconapiUrl/b2bToken - llama a
ethora-auth-use-b2b - luego prueba
ethora-b2b-app-createoethora-app-tokens-list-v2
- llama a
🧭 P1: B2B "crear app → indexar fuentes → desplegar bot" en una sola llamada
Requisitos previos:
- Configura
ETHORA_API_URL(o llama aethora-configure) - Configura
ETHORA_B2B_TOKEN(o llama aethora-configureconb2bToken) - Asegúrate de que tu backend de Ethora esté configurado con la URL/secret del servicio de IA (para la activación del bot)
Flujo sugerido:
- Llama a
ethora-auth-use-b2b - Llama a
ethora-b2b-app-bootstrap-aicon:displayName- opcional
savedAgentId - opcional
crawlUrl - opcional
docs[](base64) enableBot: true- opcional
llmProvider - opcional
llmModel
Hará lo siguiente:
- crear la app (B2B)
- establecer el contexto de la app actual (mejor esfuerzo)
- indexar fuentes mediante
/v2/sources/*(autenticación con app-token) - configurar y/o habilitar el bot (mejor esfuerzo)
Ejemplos de payloads
Mínimo (solo crear app):
{
"displayName": "Acme AI Demo",
"setAsCurrent": true
}
Crear app + rastrear un sitio web + habilitar bot:
{
"displayName": "Acme AI Demo",
"savedAgentId": "6790abc1234567890def1111",
"crawlUrl": "https://example.com",
"followLink": true,
"enableBot": true,
"botTrigger": "/bot",
"llmProvider": "openai",
"llmModel": "gpt-4o-mini"
}
Crear app + subir documentos + habilitar bot:
{
"displayName": "Acme AI Demo",
"docs": [
{
"name": "faq.pdf",
"mimeType": "application/pdf",
"base64": "BASE64_PDF_CONTENT_HERE"
}
],
"enableBot": true,
"llmProvider": "openai",
"llmModel": "gpt-4o-mini"
}
Aprovisionar app + token + salas predeterminadas + configuración del bot:
{
"displayName": "Acme Support",
"savedAgentId": "6790abc1234567890def1111",
"tokenLabels": ["default", "staging"],
"rooms": [
{ "title": "General" },
{ "title": "Support", "pinned": true }
],
"enableBot": true,
"botTrigger": "/bot",
"botPrompt": "You are the Acme support assistant.",
"botGreetingMessage": "Hello. How can I help?",
"llmProvider": "openai",
"llmModel": "gpt-4o-mini"
}
Nota sobre proveedor/modelo:
- Los valores comunes son
openaiyopenai-compatible. - El proveedor/modelo efectivo también debe estar habilitado por tu backend de Ethora + entorno del servicio de IA.
🤖 Bucle de automatización de apps
Una vez que ya tengas una app seleccionada con autenticación appToken:
- llama a
ethora-auth-use-app - llama a
ethora-bot-get-v2para inspeccionar el estado actual del bot y la configuración del prompt - llama a
ethora-sources-site-list-v2yethora-sources-docs-list-v2para inspeccionar las fuentes indexadas - llama a
ethora-sources-site-tags-update-v2oethora-sources-docs-tags-update-v2para organizar la recuperación por etiquetas - llama a
ethora-chats-message-v2/ethora-chats-history-v2si tu backend expone la superficie de automatización de chat en el mismo host de la API
Ejemplo: aplicar etiquetas de recuperación a una fuente rastreada
{
"sourceId": "6790abc1234567890def1234",
"tags": ["support", "faq", "billing"]
}
Ejemplo: aplicar etiquetas de recuperación a un documento indexado
{
"docId": "6790abc1234567890def1235",
"tags": ["support", "faq"]
}
🛡️ Notas de seguridad
- Nunca codifiques claves de API en configuración compartida. Prefiere almacenes de secretos del lado del cliente.
- Usa claves de privilegio mínimo y considera listas permitidas/límites de tasa en tu backend de Ethora.
- Rota las credenciales regularmente en uso de producción.
Escaneos de seguridad en CI (solo informe)
Este repositorio ejecuta escaneos de solo informe en pushes/PRs:
- gitleaks para escaneo de secretos
- semgrep para SAST básico
🧰 Desarrollo
Clona y ejecuta localmente:
git clone https://github.com/dappros/ethora-mcp-server.git
cd ethora-mcp-server
npm install
npm run build
npm start
Scripts sugeridos (si no están presentes):
{
"scripts": {
"build": "tsc -p .",
"start": "node dist/index.js",
"dev": "tsx src/index.ts"
}
}
❓ Solución de problemas
- El cliente no puede conectarse: Asegúrate de que
npx @ethora/mcp-serverse ejecute localmente sin errores. Verifica Node ≥ 18. - Errores de autenticación: Verifica que
ETHORA_BASE_URLy cualquier secreto requerido estén configurados en el entorno del cliente. - Herramientas faltantes: Reinicia el cliente MCP e inspecciona los registros del servidor para ver errores de registro.
- Red: Confirma el acceso saliente desde el IDE a tu host de Ethora.
🔗 Repositorios relacionados
- Ethora Chat Component — nuestro componente de chat React usado en widgets y apps independientes https://github.com/dappros/ethora-chat-component
- Ethora WP Plugin — integración con WordPress
https://github.com/dappros/ethora-wp-plugin - RAG Demos — ejemplos de asistentes de IA RAG
https://github.com/dappros/rag_demos
📜 Licencia
Ver LICENSE.