Ethora MCP CLI

SDK

Documentación

Servidor Ethora MCP (Protocolo de Contexto de Modelo)

Añade el servidor alojado con un clic. Inicias sesión a través de tu navegador; no hay nada que instalar ni ninguna clave que pegar.

Para Claude.ai, ChatGPT, Claude Desktop, LM Studio y cualquier otra herramienta que acepte una URL de conector, añade https://mcp.chat.ethora.com/mcp/oauth e inicia sesión. ¿Prefieres ejecutarlo tú mismo? Consulta Uso con clientes stdio.

El servidor MCP para Ethora, una plataforma de chat y mensajería de código abierto con un marco integrado de agentes de IA. Permite que Claude, ChatGPT, Cursor, Claude Code, VS Code y agentes autónomos creen aplicaciones Ethora, salas de chat, usuarios y agentes de IA, publiquen mensajes, indexen fuentes RAG y generen incrustaciones de widgets de chat para sitios web, todo mediante llamadas a herramientas.

Parte del ecosistema del SDK de Ethora. Actualizaciones entre SDK: Notas de versión. Cambios de paquetes: CHANGELOG.md.

npm: https://www.npmjs.com/package/@ethora/mcp-server
Registro MCP: io.github.dappros/ethora-mcp-server (https://registry.modelcontextprotocol.io/)
API de Ethora (Swagger): https://api.chat.ethora.com/api-docs/#/

Tres formas de usarlo

	Dónde se ejecuta	Mejor para
Alojado (Ethora Cloud)	`https://mcp.chat.ethora.com/mcp` (producción; `https://mcp.chat-qa.ethora.com/mcp` es la instancia de control de calidad)	Claude.ai, ChatGPT, Claude Code, Cursor y agentes que se comunican con Ethora Cloud sin instalación local
Autoalojado	Se incluye con el despliegue del monoservidor de Ethora; habilita `services.mcp.enabled` en `deploy.yml` y se sirve en `mcp.<your domain>/mcp`	Instalaciones de Ethora dedicadas o locales; el tráfico de agentes nunca sale de tu infraestructura
CLI stdio	`npx -y @ethora/mcp-server` en tu máquina, configurado con variables de entorno	Desarrollo local, CI y clientes que lanzan un comando

Los modos alojado y autoalojado son el mismo servidor iniciado con ETHORA_MCP_TRANSPORT=http. Cada sesión MCP tiene estado privado en memoria: el inicio de sesión, la aplicación seleccionada o los tokens de un cliente nunca son visibles para otra sesión.

Inicio rápido en 60 segundos

Claude.ai o ChatGPT (conector personalizado). En la aplicación web de Ethora, abre Cuenta y luego la pestaña Asistentes de IA, crea una clave de API y copia la URL de conector personal que muestra (https://mcp.chat.ethora.com/mcp/k/<key>). Pégala como conector personalizado. Cada conversación se autentica sin paso de inicio de sesión. Para un conector listado que usa el inicio de sesión OAuth del proveedor, la URL es https://mcp.chat.ethora.com/mcp/oauth.

Claude Code.

# with a personal connector URL (no headers needed)
claude mcp add --transport http ethora https://mcp.chat.ethora.com/mcp/k/<your API key>

# or the open endpoint plus a Bearer header
claude mcp add --transport http ethora https://mcp.chat.ethora.com/mcp --header "Authorization: Bearer <your API key>"

Cursor, VS Code y cualquier cliente que acepte una URL y encabezados.

{
  "mcpServers": {
    "ethora": {
      "url": "https://mcp.chat.ethora.com/mcp",
      "headers": { "Authorization": "Bearer <your API key>" }
    }
  }
}

Agentes autónomos sin cuenta todavía. Conéctate a https://mcp.chat.ethora.com/mcp sin credenciales y llama a ethora-user-register con un correo electrónico, nombre y apellido. Crea la cuenta, inicia la sesión y devuelve una contraseña generada más una clave de API y connectorUrl exactamente una vez. Guarda la clave y vuelve a conectarte más tarde con el encabezado Bearer o la URL personal; no se necesita nada más, ni navegador ni confirmación por correo.

CLI stdio.

ETHORA_API_URL=https://api.chat.ethora.com/v1 ETHORA_APP_JWT="JWT <your app jwt>" npx -y @ethora/mcp-server

Luego pide a tu agente que llame a ethora-status, ethora-user-login (o ethora-user-register) y ethora-app-list. Si te pierdes en algún punto, llama a ethora-help: lee el estado actual y devuelve las siguientes llamadas recomendadas.

Puntos de entrada y autenticación

Punto de entrada	Quién proporciona la identidad	Cliente típico
`/mcp` (añade `?tools=all` para listar todas las herramientas de antemano)	Nadie al conectar. Llama a `ethora-user-login` o `ethora-user-register` dentro de la sesión, o envía `Authorization: Bearer <token>` en cada solicitud (clave de API de usuario, token de aplicación o token B2B; el servidor elige el modo de autenticación según el tipo de token)	Agentes, Claude Code, Cursor, conectores añadidos como "sin autenticación"
`/mcp/k/<api-key>`	La clave en la ruta, aplicada como un encabezado Bearer	Conectores personalizados de Claude.ai y ChatGPT, que aceptan una URL pero no encabezados
`/mcp/oauth`	Un token de acceso OAuth 2.1 obtenido a través del servidor de autorización de Ethora (registro dinámico de clientes, PKCE, ámbitos de acceso `read`, `write`, `admin`, más los ámbitos de identidad `openid` y `email` para directorios que los requieran)	Directorios de conectores (Claude, ChatGPT); los proveedores ejecutan el flujo de inicio de sesión ellos mismos
stdio	Variables de entorno `ETHORA_APP_JWT` (arranque de inicio de sesión/registro) y opcional `ETHORA_B2B_TOKEN`, o `ethora-session-configure` en tiempo de ejecución	CLI local

Mantente en modo de autenticación de usuario en el servidor alojado (ethora-status muestra authMode: user). Los modos de token de aplicación y B2B existen para integraciones de servidor; las rutas de agentes y salas rechazan tokens de aplicación.

Claves de API

ethora-api-key-create { name?, ttlDays? } genera una clave (90 días por defecto, máximo 365), mostrada una sola vez junto con connectorUrl. ethora-user-register genera una por defecto y ethora-user-login { createApiKey: true } bajo solicitud.
ethora-api-key-list muestra id, nombre, fecha de creación y expiración, nunca el valor. ethora-api-key-revoke { id } la invalida inmediatamente: la siguiente solicitud con esa clave falla con REFRESH_RECORD_NOT_FOUND.
Las mismas claves se gestionan en la aplicación web de Ethora en Cuenta, Asistentes de IA, donde se muestran la URL personal, una línea para Claude Code y una configuración de Cursor con botones de copiar.
Una clave actúa como el usuario. Trata la URL personal como una contraseña: no compartas capturas de pantalla de ella, revócala si se filtra. El servidor nunca registra las URLs de solicitud, y la plantilla nginx del monoservidor registra solo método y estado en el host MCP.

OAuth 2.1 (`/mcp/oauth`)

Establece ETHORA_MCP_AUTH_ISSUER a la URL pública de la API de Ethora que aloja el servidor de autorización (el despliegue del monoservidor lo establece). El servidor MCP entonces:

sirve metadatos de recursos protegidos RFC 9728 en /.well-known/oauth-protected-resource y /.well-known/oauth-protected-resource/mcp/oauth, nombrando el servidor de autorización y los tres ámbitos;
responde a solicitudes no autenticadas en /mcp/oauth con 401 y WWW-Authenticate: Bearer resource_metadata="...", que es cómo los clientes descubren el flujo;
valida cada token contra la API una vez por sesión (cacheado cinco minutos) y aplica el scope del token por herramienta: las herramientas de solo lectura necesitan read, las herramientas destructivas necesitan admin, todo lo demás necesita write. search, fetch, ethora-help, ethora-status y ethora-doctor no necesitan ámbito. Los tokens sin declaración de ámbito (claves de API) obtienen acceso completo;
oculta las herramientas de identidad (ethora-user-login, ethora-user-register, ethora-session-configure, ethora-auth-mode-set, ethora-auth-mode-set, ethora-api-key-create, ethora-api-key-list, ethora-api-key-revoke) porque el token ya fija quién eres.

El servidor de autorización en sí es parte del backend de Ethora: <issuer>/.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize (una página de consentimiento con inicio de sesión, creación de cuenta e inicio de sesión con Google), /oauth/token, /oauth/revoke y /oauth/userinfo. Los usuarios ven y desconectan las concesiones OAuth en Cuenta, Asistentes de IA, Aplicaciones de IA conectadas. Cuando ETHORA_MCP_AUTH_ISSUER no está establecido, ambas rutas OAuth devuelven 404 y el descubrimiento las omite.

Ámbitos de identidad. Algunos directorios (ChatGPT) requieren la superficie mínima de OpenID Connect sobre OAuth 2.1: los ámbitos openid y email y un endpoint userinfo que devuelve sub, email y email_verified. Estos ámbitos no otorgan acceso a aplicaciones o datos; solo permiten que el cliente vea quién inició sesión, y la página de consentimiento lo dice en palabras simples. No hay tokens de ID ni JWKS, porque nada los consume.

La confirmación de correo es opcional. Ethora nunca bloquea el registro o el panel en una dirección confirmada. Cuando un cliente solicita los ámbitos de identidad y la dirección de la cuenta aún no está confirmada, la página de consentimiento añade un paso: enviar el enlace de confirmación, continuar después de confirmar, o continuar sin compartir la dirección (los ámbitos de identidad se eliminan de la concesión y todo lo demás continúa). Los inicios de sesión con Google llegan confirmados y omiten el paso. La misma confirmación se puede enviar desde Cuenta, Asistentes de IA en la aplicación web.

Qué pueden hacer los agentes

El recorrido de extremo a extremo que un nuevo usuario normalmente solicita, con las herramientas en orden:

ethora-user-register (o ethora-user-login) para obtener una sesión autenticada y una clave de API.
ethora-app-create { displayName } y luego ethora-app-select { appId } para hacer que la nueva aplicación sea la actual.
ethora-chat-create { title } para crear una sala de grupo. El resultado contiene el JID de la sala ${appId}_${chatId}; cada herramienta de sala acepta el JID o el chatId simple.
ethora-agent-create { name, prompt, ... } para crear una persona de agente de IA en esa aplicación.
ethora-agent-invite { agentIdOrAddress, chatJid } para poner al agente en la sala. Se genera una instancia de bot en vivo, sin necesidad de reiniciar.
ethora-message-send { text, roomJid, waitForReplySec: 45 } para publicar un mensaje y esperar la respuesta del agente, devuelta como replies. ethora-chat-history lee la sala después.
ethora-agent-activate { agentId, chatJid } para hacer que ese agente sea el respondedor predeterminado de la aplicación, luego ethora-widget-snippet-get para la etiqueta <script> que coloca el widget de chat de IA en un sitio web.

ethora-help { goal } devuelve esto y las otras recetas (user-login, broadcast, sources-ingest, files-upload, bot-manage, chat-test, widget, b2b-bootstrap-ai) con las llamadas completadas para el estado actual, y ethora-recipe-run las ejecuta.

Convenciones del primer minuto

Cada herramienta de creación responde de la misma manera. ethora-app-create, ethora-chat-create, ethora-agent-create devuelven el objeto API sin procesar más created (kind, id, name, y jid o address donde sea relevante) y next, de dos a cuatro llamadas sugeridas con argumentos completados. ethora-app-create también devuelve dashboardUrl, la aplicación en el panel web.
ethora-help { goal } tiene una receta para cada trabajo principal: new-app, in-app-chat, multi-agent-room, widget, chat-test, más los objetivos de integración de servidor. Cada una devuelve las llamadas en orden con argumentos para copiar.
Quién habló. ethora-message-send responde y las filas de ethora-chat-history llevan senderName y senderKind (human, agent, app), por lo que una sala multiagente se lee como "Freud: ..., Jung: ..." en lugar de ids de instancia.
La búsqueda entiende la intención. search mapea las frases que usa la gente ("añadir chat a mi aplicación React", "varios agentes hablando entre sí", "webhook cuando llega un mensaje") a los documentos que las responden, y doc:not-available dice claramente qué no está expuesto a través de MCP y dónde vive en su lugar. Los documentos completos se pueden obtener por su id simple (doc:recipes, doc:chat-component-quickstart, doc:sdk-backend-quickstart, doc:auth-map).

Documentación dentro del servidor

instructions en el resultado de inicialización le dicen al asistente cómo funciona la identidad en el punto de entrada por el que se conectó: el endpoint abierto explica inicio de sesión y registro, las sesiones de URL personal y Bearer se informan de que ya están autenticadas y nunca deben pedir contraseña o clave, las sesiones OAuth lo mismo más cómo reaccionar a INSUFFICIENT_SCOPE.
search { query } y fetch { id } (la convención del conector de ChatGPT) buscan en un corpus en memoria: el mapa de autenticación, inicios rápidos, recetas, una guía de inicio alojada, una guía de claves de API y una entrada de referencia por herramienta con sus entradas. Funcionan sin autenticación.
Recursos ethora://docs/auth-map, ethora://docs/chat-component/quickstart, ethora://docs/sdk-backend/quickstart, ethora://docs/recipes y prompts ethora-auth-map, ethora-vite-quickstart, ethora-nextjs-quickstart, ethora-backend-sdk-quickstart, ethora-recipes, ethora-agents-quickstart.

Grupos de herramientas

Una sesión lista solo el grupo core al principio: 24 herramientas que cubren todo el recorrido de "iniciar sesión, crear una aplicación, añadir salas y mensajes, crear y activar un agente, darle una base de conocimiento, obtener el widget", una variante por operación. Los otros grupos están registrados pero ocultos, lo que mantiene tools/list alrededor de 40 KB en lugar de 120 KB y da a los asistentes una lista corta para elegir.

Tres formas de obtener más:

ethora-tools-enable { group } habilita un grupo para la sesión (o { group: "all" }); el servidor envía tools/list_changed y el cliente se actualiza. Sin argumentos, devuelve el catálogo con conteos.
Llamar a una herramienta oculta por su nombre habilita su grupo y la ejecuta, por lo que un nombre aprendido de la documentación o de una sesión anterior nunca se rechaza.
?tools=all en la URL del endpoint (alojado) o ETHORA_MCP_TOOLS=all (stdio) lista todo de antemano.

search y fetch también describen herramientas ocultas; cada documento de herramienta nombra su grupo, y doc:tool-groups es el catálogo. Las variantes heredadas y asíncronas llevan una primera línea que nombra al hermano preferido.

Grupo	Qué cubre	Herramientas
`core` (listado por defecto)	Iniciar sesión o registrarse, crear una aplicación, añadir salas y mensajes, crear y activar un agente de IA, darle una base de conocimiento, obtener el widget del sitio web. Siempre listado.	`ethora-status`, `ethora-help`, `ethora-feedback-submit`, `ethora-tools-enable`, `search`, `fetch`, `ethora-user-register`, `ethora-user-login`, `ethora-api-key-create`, `ethora-app-create`, `ethora-app-list`, `ethora-app-select`, `ethora-app-update`, `ethora-chat-create`, `ethora-message-send`, `ethora-chat-history`, `ethora-agent-create`, `ethora-agent-list`, `ethora-agent-update`, `ethora-agent-invite`, `ethora-agent-activate`, `ethora-source-site-crawl-wait`, `ethora-source-doc-upload`, `ethora-widget-snippet-get`
`keys`	Listar y revocar claves de API, revelar las credenciales de una aplicación, acuñar y rotar tokens de aplicación.	`ethora-api-key-list`, `ethora-api-key-revoke`, `ethora-app-credentials-reveal`, `ethora-app-token-create`, `ethora-app-token-list`, `ethora-app-token-revoke`, `ethora-app-token-rotate`
`session`	Diagnósticos, recetas y cambio del modo de autenticación de la sesión (token de aplicación, token B2B) para integraciones de servidor.	`ethora-doctor`, `ethora-recipe-run`, `ethora-session-configure`, `ethora-auth-mode-set`, `ethora-auth-mode-set`, `ethora-auth-mode-set`
`apps-admin`	Eliminar, exportar e importar aplicaciones completas; inspeccionar salas predeterminadas.	`ethora-app-delete`, `ethora-app-export`, `ethora-app-import`, `ethora-app-rooms-list`, `ethora-app-rooms-list`
`rooms`	Eliminar salas, transmitir a muchas salas, buscar mensajes, leer el contexto de mensajes y los conteos de no leídos.	`ethora-chat-delete`, `ethora-broadcast-send`, `ethora-broadcast-job-start`, `ethora-broadcast-job-wait`, `ethora-message-search`, `ethora-message-context`, `ethora-chat-unread-counts`
`agents-admin`	Inspeccionar, clonar, eliminar, exportar e importar agentes; editar el alma y la visibilidad de un agente.	`ethora-agent-get`, `ethora-agent-clone`, `ethora-agent-delete`, `ethora-agent-export`, `ethora-agent-import`, `ethora-agent-visibility-set`, `ethora-agent-soul-set`, `ethora-agent-soul-append`
`sources`	Mantenimiento de la base de conocimiento: trabajos asíncronos de rastreo y reindexación, listar y etiquetar sitios y documentos, eliminar URLs y documentos.	`ethora-source-site-crawl`, `ethora-source-site-reindex`, `ethora-source-site-reindex-wait`, `ethora-source-site-list`, `ethora-source-site-tags-update`, `ethora-source-site-url-delete`, `ethora-source-site-url-delete-batch`, `ethora-source-doc-list`, `ethora-source-doc-tags-update`, `ethora-source-doc-delete`
`users-files`	Crear usuarios por lotes y subir, obtener o eliminar archivos.	`ethora-user-batch-create`, `ethora-user-batch-job-start`, `ethora-user-batch-job-wait`, `ethora-file-upload`, `ethora-file-get`, `ethora-file-delete`
`legacy-bot`	El bot por aplicación de las aplicaciones creadas en el panel antes del framework de agentes, y las herramientas de documentos pre-v2. Prefiere las herramientas de agentes y fuentes para cualquier cosa nueva.	`ethora-bot-get`, `ethora-bot-update`, `ethora-bot-enable`, `ethora-bot-disable`, `ethora-bot-widget-get`, `ethora-bot-history`, `ethora-bot-message-send`, `ethora-bot-instance-list`, `ethora-bot-instance-status-set`, `ethora-bot-instance-diagnose`, `ethora-bot-instance-leave`, `ethora-bot-instance-test`, `ethora-bot-enable-b2b`, `ethora-source-doc-upload-legacy`, `ethora-source-doc-delete-legacy`
`b2b`	Aprovisionamiento servidor a servidor con un token B2B, además de generadores de código y configuración para integraciones.	`ethora-b2b-app-create`, `ethora-b2b-app-provision`, `ethora-b2b-app-bootstrap-ai`, `ethora-b2b-runbook-generate`, `ethora-env-examples-generate`, `ethora-chat-component-app-generate`, `ethora.b2b.auth.use`, `ethora.b2b.app.create`, `ethora.b2b.bot.enable`, `ethora.b2b.broadcast.wait`, `ethora.b2b.app.bootstrap-ai`
`wallet`	Saldo de billetera y transferencia ERC-20. Solo local (stdio); nunca se ofrece en el servidor alojado.	`ethora-wallet-balance-get`, `ethora-wallet-erc20-transfer`

Las herramientas de eliminación de aplicaciones y de borrado masivo solo se registran cuando ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true (el despliegue de monoserver lo establece; el valor predeterminado de stdio está desactivado). Las herramientas de alias (ethora.b2b.*, ethora-bot-message-send, ethora-bot-history) están desactivadas por defecto (ETHORA_MCP_ENABLE_ALIASES=true para exponerlas); las herramientas canónicas cubren el mismo terreno.

Widget del sitio web

ethora-widget-snippet-get devuelve la etiqueta para el widget de chat de IA incrustable:

<script id="chat-content-assistant" src="https://widget.<your domain>/assistant.js"
  data-app-id="<appId>" data-api-base="https://api.<your domain>" data-bot-name="Helper" defer></script>

El widget responde con el bot activo de la aplicación (defaultBotInstanceId). En una aplicación creada a través de la API, ejecuta ethora-agent-create, ethora-chat-create, ethora-agent-invite y ethora-agent-activate { agentId, chatJid } primero; la herramienta lista estos requisitos previos y ethora-help { goal: "widget" } los recorre. La activación se ejecuta en autenticación de usuario estableciendo la instancia de bot predeterminada de la aplicación (lo que hace el menú desplegable de Widget de IA del administrador). Hasta que un bot esté activo, el endpoint de sesión del widget responde AI_BOT_NOT_CONFIGURED. ethora-chat-component-app-generate produce un App.tsx de React para @ethora/chat-component en su lugar.

Configuración

Variables de entorno (stdio y alojado)

Variable	Significado
`ETHORA_API_URL`	URL completa de la API, p. ej. `https://api.chat.ethora.com/v1` (predeterminado). En un servidor alojado está fija para todas las sesiones
`ETHORA_BASE_URL`	Alternativa solo para host a `ETHORA_API_URL`; se añade `/v1`
`ETHORA_APP_JWT`	JWT de aplicación usado solo por inicio de sesión y registro (`ETHORA_APP_TOKEN` es un alias heredado)
`ETHORA_APP_DOMAIN_NAME`	`domainName` base de la aplicación; cuando `ETHORA_APP_JWT` está vacío, el servidor obtiene el JWT de la aplicación desde `GET /v1/apps/get-config?domainName=...` al inicio
`ETHORA_B2B_TOKEN`	Token de servidor B2B para rutas de actor de inquilino `x-custom-token`
`ETHORA_MCP_TOOLS`	`all` lista todas las herramientas desde el principio en lugar del grupo principal (stdio; el alojado usa `?tools=all` en la URL)
`ETHORA_MCP_ENABLE_DANGEROUS_TOOLS`	`true` registra las herramientas de eliminación de aplicaciones, transferencia de billetera y borrado masivo (predeterminado desactivado)
`ETHORA_MCP_OPENAI_APPS_CHALLENGE`	Solo alojado. Token emitido por el portal de aplicaciones de OpenAI para verificación de dominio; se sirve textualmente en `/.well-known/openai-apps-challenge` (404 cuando no está configurado)
`ETHORA_MCP_ENABLE_ALIASES`	`true` expone las herramientas de alias con espacio de nombres de puntos (predeterminado desactivado)

Solo modo alojado

Variable	Significado
`ETHORA_MCP_TRANSPORT`	`stdio` (predeterminado) o `http`; `--http` en la línea de comandos hace lo mismo
`ETHORA_MCP_HTTP_HOST`, `ETHORA_MCP_HTTP_PORT`	Dirección de enlace, predeterminado `127.0.0.1:3030`; pon nginx delante
`ETHORA_MCP_PUBLIC_URL`	URL base pública anunciada en el descubrimiento y usada para `connectorUrl`, p. ej. `https://mcp.chat.ethora.com/mcp`
`ETHORA_MCP_TRUST_PROXY`	`true` toma la IP del cliente desde `X-Forwarded-For`; se reenvía a la API para que los límites por IP se apliquen por llamante
`ETHORA_MCP_SESSION_TTL_MS`	Desalojo de sesión inactiva, predeterminado 4 horas
`ETHORA_MCP_AUTH_ISSUER`	URL pública del servidor de autorización OAuth (el host de la API de Ethora); habilita `/mcp/oauth`
`ETHORA_MCP_WIDGET_URL`	URL base del widget de chat de IA alojado (`<url>/assistant.js`) para `ethora-widget-snippet-get`
`ETHORA_MCP_PUBLIC_API_URL`	Base de API pública a la que los navegadores pueden acceder, emitida como `data-api-base`; retrocede a `ETHORA_MCP_AUTH_ISSUER`, luego a un `ETHORA_API_URL` no de bucle local

Un archivo .env en el directorio de trabajo se carga al inicio; las variables de entorno reales ganan. Las credenciales también se pueden establecer por sesión con ethora-session-configure (solo en memoria; en un servidor alojado apiUrl no se puede cambiar).

Endpoints (alojado)

Ruta	Propósito
`POST\|GET\|DELETE /mcp`	Endpoint MCP HTTP transmisible, abierto
`POST\|GET\|DELETE /mcp/k/<api-key>`	Igual, autenticado por la clave en la ruta
`POST\|GET\|DELETE /mcp/oauth`	Igual, token Bearer requerido, ámbitos aplicados
`GET /healthz`	`{ ok, sessions, version, appJwtReady, oauth }`
`GET /.well-known/mcp` y `GET /`	JSON de descubrimiento: endpoint, transporte, opciones de autenticación, metadatos OAuth
`GET /.well-known/oauth-protected-resource[/mcp/oauth]`	Metadatos de recurso protegido RFC 9728

Envoltura de respuesta

Cada herramienta devuelve texto JSON en una forma: éxito { ok: true, ts, meta, data }, fallo { ok: false, ts, meta, error } donde error lleva code (el código propio de la API cuando lo tiene), message, httpStatus, requestId y un hint de una línea.

Uso con clientes stdio

Cada cliente stdio ejecuta npx -y @ethora/mcp-server; pasa las credenciales como variables de entorno (preferido) o llama a ethora-session-configure para una prueba local rápida (sus argumentos terminan en la transcripción). Para el modo alojado, usa los botones de un clic en la parte superior de este README, o el formulario de URL en el inicio rápido. Botones de un clic para el paquete stdio:

Cursor

{ "mcpServers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } }

VS Code (y modo agente de GitHub Copilot)

.vscode/mcp.json (nota: la clave es servers):

{ "servers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } }

Claude Code

claude mcp add ethora -e ETHORA_API_URL=https://api.chat.ethora.com/v1 -e ETHORA_APP_JWT="JWT <your app jwt>" -- npx -y @ethora/mcp-server

Añade --scope user para que esté disponible en cada proyecto; verifica con claude mcp list.

Claude Desktop

Configuración, Desarrollador, Editar Configuración (claude_desktop_config.json):

{ "mcpServers": { "ethora": { "command": "npx", "args": ["-y", "@ethora/mcp-server"] } } }

Gemini CLI, Windsurf, Cline

El mismo bloque mcpServers de arriba en ~/.gemini/settings.json, ~/.codeium/windsurf/mcp_config.json o cline_mcp_settings.json.

Codex CLI

~/.codex/config.toml (la tabla es mcp_servers con un guion bajo):

[mcp_servers.ethora]
command = "npx"
args = ["-y", "@ethora/mcp-server"]

Contenedor

docker build -t ethora-mcp-server .
docker run -i --rm -e ETHORA_API_URL=https://api.chat.ethora.com/v1 -e ETHORA_APP_JWT="JWT <your app jwt>" ethora-mcp-server

Añade -e ETHORA_MCP_TRANSPORT=http -e ETHORA_MCP_HTTP_HOST=0.0.0.0 -p 3030:3030 para ejecutar el modo alojado en un contenedor.

Aprovisionamiento B2B (integraciones de servidor)

Con ETHORA_B2B_TOKEN configurado, ethora-auth-mode-set cambia la sesión a autenticación de actor de inquilino y ethora-b2b-app-bootstrap-ai crea una aplicación, indexa fuentes (crawlUrl, docs[] como base64) y configura su bot en una sola llamada, con llmProvider y llmModel opcionales. ethora-b2b-app-provision añade tokens de aplicación y salas predeterminadas. ethora-user-batch-create más ethora-user-batch-job-wait aprovisionan usuarios de forma asíncrona y ethora-broadcast-send más ethora-broadcast-job-wait envían un mensaje a muchas salas. ethora-b2b-runbook-generate imprime el orden de llamadas para tu propia automatización.

Solución de problemas

Síntoma	Significado y solución
`TOKEN_MISSING` (401)	La sesión no tiene token de usuario. Llama a `ethora-user-login` o `ethora-user-register`, o conéctate con un encabezado Bearer o URL personal
`REFRESH_RECORD_NOT_FOUND` (401)	La clave de API o el token fue revocado. Crea una nueva clave
`INSUFFICIENT_SCOPE` (403) en `/mcp/oauth`	La concesión OAuth carece del ámbito que la herramienta necesita (`read`, `write` o `admin`). Reconéctate y aprueba el ámbito más amplio
`This tool requires app-token auth` o `AUTH_USER_REQUIRED`	Modo de autenticación incorrecto. En el servidor alojado, permanece en modo usuario (`ethora-auth-mode-set`); el modo token de aplicación es solo para `/v2/bot` y rutas de widget
`AI_BOT_NOT_CONFIGURED` del widget	No hay bot activo en la aplicación. Ejecuta los pasos del agente, invitación y `ethora-agent-activate`, luego recarga la página
`BOT_NOT_INITIALIZED` (422) desde `ethora-bot-*`	La aplicación no tiene bot heredado por aplicación; usa las herramientas de agentes en su lugar
`AGENT_NOT_FOUND` o `APP_NOT_FOUND` (404)	ID incorrecto o la aplicación no fue seleccionada; `ethora-app-select` primero, o pasa `appId`
`Not Acceptable` (406) desde `/mcp`	El cliente debe aceptar tanto `application/json` como `text/event-stream`
La página de consentimiento dice `Social sign-in failed (auth/...)`	El código de Firebase entre paréntesis nombra la causa (la consola del navegador tiene el error completo). `auth/popup-blocked`: permite ventanas emergentes para el host de la API. Un mensaje sin código se corrigió en el backend el 2026-09-17; actualiza si autoalojas
El cliente no puede conectarse (stdio)	Ejecuta `npx -y @ethora/mcp-server` en una terminal y verifica Node 18 o más reciente
El servidor alojado no responde	`GET /healthz`; `appJwtReady: false` significa que el arranque del JWT de la aplicación base falló (verifica `ETHORA_APP_DOMAIN_NAME` y `ETHORA_API_URL`)

Comentarios

ethora-feedback-submit envía un informe (bug, unexpected, feature, docs, other) al equipo de Ethora desde dentro de una sesión. La razón de hacer esto a través de MCP en lugar de un formulario web es el contexto: los últimos fallos de herramientas de la sesión viajan con el informe — nombre de la herramienta, código de error y la API requestId — de modo que un informe puede vincularse con la entrada del registro del lado del servidor en lugar de volver a escribirse de memoria. Establece includeRecentErrors: false cuando el informe no esté relacionado con un fallo.

Funciona tanto si la sesión está autenticada como si no, porque el informante del que más necesitamos saber es aquel cuyo registro o credencial es lo que falló; un informe autenticado se atribuye a esa cuenta, y uno anónimo puede llevar un email para una respuesta. También está exento de la aplicación de ámbitos OAuth, por lo que una concesión de solo lectura aún puede informar de un problema.

Las claves con forma de credencial en el contexto adjunto se redactan antes de enviarse. Eso se basa en claves, por lo que no puede detectar una credencial pegada en el message de texto libre: la descripción de la herramienta indica al modelo que no ponga secretos ni datos personales de usuarios finales allí.

La entrega se configura en el lado de la API (FEEDBACK_EMAIL_TO, FEEDBACK_SLACK_WEBHOOK_URL, FEEDBACK_RETENTION_DAYS); el servidor MCP solo envía.

Atribución de uso

Las llamadas API salientes llevan X-Ethora-Client: mcp/<version> y, durante la duración de una llamada de herramienta, X-Ethora-Tool: <tool-name>. La API los registra en su registro de solicitudes como client y source: mcp:<tool>, que es como el tráfico MCP se separa de la aplicación web y se cuenta por herramienta. Los endpoints públicos no autenticados (/ping, /apps/get-config) quedan sin atribuir.

Notas de seguridad

Las credenciales se redactan de los resultados de las herramientas. appSecret, tenantSecret, appToken, contraseñas y claves similares vuelven como [redacted] de cada herramienta (los resultados entran en el contexto del modelo y en los registros del cliente). ethora-app-credentials-reveal { appId, confirm: true } revela el appToken de una aplicación a propósito y necesita el ámbito admin sobre OAuth; el App Secret solo se muestra en la pestaña de API del panel web. Las herramientas de inicio de sesión, registro y acuñación de claves API / tokens de aplicación aún devuelven su credencial una vez por diseño.
Las claves API y las URLs personales actúan como el usuario hasta que se revocan. Mantenlas en el almacén de secretos de tu cliente, nunca en configuración compartida o capturas de pantalla, y revócalas ante cualquier sospecha.
El servidor nunca registra URLs de solicitudes ni tokens. Mantén el registro de acceso de tu proxy inverso libre de rutas de solicitud para el host MCP (la plantilla nginx de monoserver lo hace).
Cualquier cosa devuelta por una herramienta es visible para el modelo y se almacena en la transcripción de la conversación; el servidor indica a los asistentes que no impriman claves ni contraseñas, y que confirmen las herramientas destructivas con el usuario.
Este repositorio ejecuta escaneos de secretos y SAST solo de informe (gitleaks, semgrep) en pushes y PRs.

Desarrollo

Números de versión

Las versiones se basan en el calendario: YY.M.patch, donde YY.M es el año y mes en que se publica la versión (26.9.5 es la quinta versión de septiembre de 2026, 26.10.0 la primera de octubre) y patch cuenta las versiones dentro del mes. Sin cero inicial en el mes, por lo que 26.10 se ordena después de 26.9 bajo semver. Los cambios disruptivos no aumentan la versión principal; reciben el siguiente parche y una entrada de changelog, y los nombres de herramientas anteriores siguen siendo invocables como alias. npm run sync-version rechaza cualquier otra forma o cualquier mes distinto del actual (ETHORA_VERSION_MONTH=YY.M anula a propósito), y el flujo de publicación lo ejecuta. 27.0.0 y 27.1.0, publicados el 2026-09-24 bajo esta regla, están obsoletos; 26.9.5 es el mismo código.

Nombres de herramientas

Desde 27.0 cada herramienta listada sigue una regla: ethora-<resource>-<verb>[-<qualifier>].

recurso es un sustantivo singular, de una o dos palabras: app, agent, chat, message, broadcast, source-site, source-doc, user, file, bot, api-key, app-token, widget, wallet, session, auth-mode, recipe, tools.
verbo es la última palabra: create, list, get, update, delete, send, set, run, reveal, upload, crawl, reindex, start, wait, enable, disable, generate.
un calificador solo sigue al verbo: -wait (forma bloqueante de un trabajo asíncrono), -batch, -legacy, -b2b.
sin sufijos de versión de API: -v2 desaparece de cada nombre. search y fetch mantienen sus nombres por convención del conector ChatGPT.

Cada nombre anterior sigue funcionando. Los nombres antiguos son alias: nunca listados por tools/list, pero una llamada a uno se reescribe a la herramienta canónica (con un argumento preestablecido cuando tres o dos herramientas se convirtieron en una, como ethora-auth-use-app convirtiéndose en ethora-auth-mode-set { mode: "app" }), por lo que las configuraciones publicadas, recetas y conversaciones guardadas siguen funcionando. Los resultados y la atribución de uso nombran la herramienta canónica. El mapeo completo está en la tabla de alias al final de este archivo y en src/toolNames.ts, que el conjunto de pruebas verifica contra el registro.

Repositorios relacionados

ethora-chat-component: el componente de chat React usado en widgets y aplicaciones independientes
ethora-monoserver: automatización de despliegue que envía este servidor como un servicio opcional (repositorio privado, disponible para clientes empresariales)
ethora-wp-plugin: integración con WordPress
rag_demos: ejemplos de asistentes de IA RAG

Puntuación de calidad y mantenimiento

Inspeccionado de forma independiente por Glama, que construye el servidor, cataloga sus herramientas y califica la calidad de las definiciones de herramientas y la actividad de mantenimiento.

Nombres de herramientas anteriores

Nombres usados antes de 27.0 y la herramienta a la que cada uno se resuelve ahora. Todos siguen siendo invocables.

Nombre anterior	Herramienta canónica
`ethora-agents-activate-v2`	`ethora-agent-activate`
`ethora-agents-clone-v2`	`ethora-agent-clone`
`ethora-agents-create-v2`	`ethora-agent-create`
`ethora-agents-delete-v2`	`ethora-agent-delete`
`ethora-agents-export-v2`	`ethora-agent-export`
`ethora-agents-get-v2`	`ethora-agent-get`
`ethora-agents-import-v2`	`ethora-agent-import`
`ethora-agent-invite-to-chat`	`ethora-agent-invite`
`ethora-agents-list-v2`	`ethora-agent-list`
`ethora-agents-update-v2`	`ethora-agent-update`
`ethora-agent-set-visibility`	`ethora-agent-visibility-set`
`ethora-app-credentials`	`ethora-app-credentials-reveal`
`ethora-app-export-v2`	`ethora-app-export`
`ethora-app-import-v2`	`ethora-app-import`
`ethora-app-get-default-rooms`	`ethora-app-rooms-list`
`ethora-app-get-default-rooms-with-app-id`	`ethora-app-rooms-list`
`ethora-app-tokens-create-v2`	`ethora-app-token-create`
`ethora-app-tokens-list-v2`	`ethora-app-token-list`
`ethora-app-tokens-revoke-v2`	`ethora-app-token-revoke`
`ethora-app-tokens-rotate-v2`	`ethora-app-token-rotate`
`ethora-auth-use-app`	`ethora-auth-mode-set` con `{"mode": "app"}`
`ethora-auth-use-b2b`	`ethora-auth-mode-set` con `{"mode": "b2b"}`
`ethora-auth-use-user`	`ethora-auth-mode-set` con `{"mode": "user"}`
`ethora.b2b.auth.use`	`ethora-auth-mode-set` con `{"mode": "b2b"}`
`ethora.b2b.app.bootstrap-ai`	`ethora-b2b-app-bootstrap-ai`
`ethora.b2b.app.create`	`ethora-b2b-app-create`
`ethora-generate-b2b-bootstrap-runbook`	`ethora-b2b-runbook-generate`
`ethora-bot-disable-v2`	`ethora-bot-disable`
`ethora-bot-enable-v2`	`ethora-bot-enable`
`ethora-b2b-bot-enable`	`ethora-bot-enable-b2b`
`ethora.b2b.bot.enable`	`ethora-bot-enable-b2b`
`ethora-bot-get-v2`	`ethora-bot-get`
`ethora-bot-history-v2`	`ethora-bot-history`
`ethora-bot-instance-diag`	`ethora-bot-instance-diagnose`
`ethora-bot-instance-leave-chat`	`ethora-bot-instance-leave`
`ethora-bot-instances-list`	`ethora-bot-instance-list`
`ethora-bot-instance-status`	`ethora-bot-instance-status-set`
`ethora-bot-instance-test-message`	`ethora-bot-instance-test`
`ethora-bot-message-v2`	`ethora-bot-message-send`
`ethora-bot-update-v2`	`ethora-bot-update`
`ethora-bot-widget-v2`	`ethora-bot-widget-get`
`ethora-chats-broadcast-job-v2`	`ethora-broadcast-job-start`
`ethora-wait-broadcast-job-v2`	`ethora-broadcast-job-wait`
`ethora.b2b.broadcast.wait`	`ethora-broadcast-job-wait`
`ethora-chats-broadcast-v2`	`ethora-broadcast-send`
`ethora-generate-chat-component-app-tsx`	`ethora-chat-component-app-generate`
`ethora-app-create-chat`	`ethora-chat-create`
`ethora-app-delete-chat`	`ethora-chat-delete`
`ethora-chats-history-v2`	`ethora-chat-history`
`ethora-unread-counts-v2`	`ethora-chat-unread-counts`
`ethora-generate-env-examples`	`ethora-env-examples-generate`
`ethora-files-delete-v2`	`ethora-file-delete`
`ethora-files-get-v2`	`ethora-file-get`
`ethora-files-upload-v2`	`ethora-file-upload`
`ethora-messages-context-v2`	`ethora-message-context`
`ethora-messages-search-v2`	`ethora-message-search`
`ethora-chats-message-v2`	`ethora-message-send`
`ethora-run-recipe`	`ethora-recipe-run`
`ethora-configure`	`ethora-session-configure`
`ethora-sources-docs-delete-v2`	`ethora-source-doc-delete`
`ethora-sources-docs-delete`	`ethora-source-doc-delete-legacy`
`ethora-sources-docs-list-v2`	`ethora-source-doc-list`
`ethora-sources-docs-tags-update-v2`	`ethora-source-doc-tags-update`
`ethora-sources-docs-upload-v2`	`ethora-source-doc-upload`
`ethora-sources-docs-upload`	`ethora-source-doc-upload-legacy`
`ethora-sources-site-crawl-v2`	`ethora-source-site-crawl`
`ethora-sources-site-crawl-v2-wait`	`ethora-source-site-crawl-wait`
`ethora-sources-site-list-v2`	`ethora-source-site-list`
`ethora-sources-site-reindex-v2`	`ethora-source-site-reindex`
`ethora-sources-site-reindex-v2-wait`	`ethora-source-site-reindex-wait`
`ethora-sources-site-tags-update-v2`	`ethora-source-site-tags-update`
`ethora-sources-site-delete-url-v2`	`ethora-source-site-url-delete`
`ethora-sources-site-delete-url-v2-batch`	`ethora-source-site-url-delete-batch`
`ethora-users-batch-create-v2`	`ethora-user-batch-create`
`ethora-users-batch-job-v2`	`ethora-user-batch-job-start`
`ethora-wait-users-batch-job-v2`	`ethora-user-batch-job-wait`
`ethora-wallet-get-balance`	`ethora-wallet-balance-get`
`ethora-widget-embed-snippet`	`ethora-widget-snippet-get`

Licencia

Consulta LICENSE.