Ethora MCP CLI

SDK de chat e mensagens e plataforma em nuvem para seus aplicativos. Suporta agentes de IA e bots RAG.

Documentação

Servidor Ethora MCP (Model Context Protocol)

Adicione o servidor hospedado com um clique. Você faz login pelo navegador; não há nada para instalar e nenhuma chave para colar.

Para Claude.ai, ChatGPT, Claude Desktop, LM Studio e qualquer outra ferramenta que aceite uma URL de conector, adicione https://mcp.chat.ethora.com/mcp/oauth e faça login. Prefere executar você mesmo? Veja Usando com clientes stdio.

O servidor MCP para Ethora, uma plataforma de chat e mensagens de código aberto com um framework integrado de agentes de IA. Ele permite que Claude, ChatGPT, Cursor, Claude Code, VS Code e agentes autônomos criem apps Ethora, salas de chat, usuários e agentes de IA, publiquem mensagens, indexem fontes RAG e gerem embeds de widget de chat para sites, tudo por chamadas de ferramentas.

Parte do ecossistema Ethora SDK. Atualizações entre SDKs: Notas de versão. Alterações de pacotes: CHANGELOG.md.

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

Três formas de usar

	Onde roda	Melhor para
Hospedado (Ethora Cloud)	`https://mcp.chat.ethora.com/mcp` (produção; `https://mcp.chat-qa.ethora.com/mcp` é a instância de QA)	Claude.ai, ChatGPT, Claude Code, Cursor e agentes que falam com a Ethora Cloud sem instalação local
Auto-hospedado	Acompanha a implantação do monoserver Ethora; habilite `services.mcp.enabled` em `deploy.yml` e ele é servido em `mcp.<your domain>/mcp`	Instalações Ethora dedicadas ou on-premise; o tráfego de agentes nunca sai da sua infraestrutura
CLI stdio	`npx -y @ethora/mcp-server` na sua máquina, configurado com variáveis de ambiente	Desenvolvimento local, CI e clientes que iniciam um comando

Os modos hospedado e auto-hospedado são o mesmo servidor iniciado com ETHORA_MCP_TRANSPORT=http. Cada sessão MCP tem estado privado em memória: o login, o app selecionado ou os tokens de um cliente nunca são visíveis para outra sessão.

Início rápido em 60 segundos

Claude.ai ou ChatGPT (conector personalizado). No app web Ethora, abra Conta e depois a aba Assistentes de IA, crie uma chave de API e copie a URL de conector pessoal que ela mostra (https://mcp.chat.ethora.com/mcp/k/<key>). Cole como conector personalizado. Cada conversa é autenticada sem etapa de login. Para um conector listado que usa o login OAuth do fornecedor, a URL é 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 e qualquer cliente que aceite URL e cabeçalhos.

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

Agentes autônomos sem conta ainda. Conecte-se a https://mcp.chat.ethora.com/mcp sem credenciais e chame ethora-user-register com um e-mail, nome e sobrenome. Ele cria a conta, autentica a sessão e retorna uma senha gerada, além de uma chave de API e connectorUrl exatamente uma vez. Guarde a chave e reconecte-se depois com o cabeçalho Bearer ou a URL pessoal; nada mais é necessário, sem navegador e sem confirmação por e-mail.

CLI stdio.

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

Depois peça ao seu agente para chamar ethora-status, ethora-user-login (ou ethora-user-register) e ethora-app-list. Se perder em algum ponto, chame ethora-help: ele lê o estado atual e retorna as próximas chamadas recomendadas.

Pontos de entrada e autenticação

Ponto de entrada	Quem fornece a identidade	Cliente típico
`/mcp` (adicione `?tools=all` para listar todas as ferramentas antecipadamente)	Ninguém no momento da conexão. Chame `ethora-user-login` ou `ethora-user-register` dentro da sessão, ou envie `Authorization: Bearer <token>` em cada requisição (chave de API de usuário, token de app ou token B2B; o servidor escolhe o modo de autenticação pelo tipo de token)	Agentes, Claude Code, Cursor, conectores adicionados como "sem autenticação"
`/mcp/k/<api-key>`	A chave no caminho, aplicada como cabeçalho Bearer	Conectores personalizados do Claude.ai e ChatGPT, que aceitam URL mas não cabeçalhos
`/mcp/oauth`	Um token de acesso OAuth 2.1 obtido pelo servidor de autorização Ethora (registro dinâmico de cliente, PKCE, escopos de acesso `read`, `write`, `admin`, além dos escopos de identidade `openid` e `email` para diretórios que os exigem)	Diretórios de conectores (Claude, ChatGPT); os fornecedores executam o fluxo de login eles mesmos
stdio	Variáveis de ambiente `ETHORA_APP_JWT` (bootstrap de login/registro) e `ETHORA_B2B_TOKEN` opcional, ou `ethora-session-configure` em tempo de execução	CLI local

Permaneça no modo de autenticação de usuário no servidor hospedado (ethora-status mostra authMode: user). Os modos de token de app e B2B existem para integrações de servidor; as rotas de agentes e salas rejeitam tokens de app.

Chaves de API

ethora-api-key-create { name?, ttlDays? } gera uma chave (padrão 90 dias, máximo 365), mostrada uma única vez junto com connectorUrl. ethora-user-register gera uma por padrão e ethora-user-login { createApiKey: true } sob solicitação.
ethora-api-key-list mostra id, nome, data de criação e expiração, nunca o valor. ethora-api-key-revoke { id } a invalida imediatamente: a próxima requisição com essa chave falha com REFRESH_RECORD_NOT_FOUND.
As mesmas chaves são gerenciadas no app web Ethora em Conta, Assistentes de IA, onde a URL pessoal, um comando de uma linha para Claude Code e uma configuração para Cursor são mostrados com botões de copiar.
Uma chave age como o usuário. Trate a URL pessoal como uma senha: não compartilhe capturas de tela dela, revogue-a se vazar. O servidor nunca registra URLs de requisição, e o template nginx do monoserver registra apenas método e status no host MCP.

OAuth 2.1 (`/mcp/oauth`)

Defina ETHORA_MCP_AUTH_ISSUER para a URL pública da API Ethora que hospeda o servidor de autorização (a implantação do monoserver a define). O servidor MCP então:

serve metadados de recurso protegido RFC 9728 em /.well-known/oauth-protected-resource e /.well-known/oauth-protected-resource/mcp/oauth, nomeando o servidor de autorização e os três escopos;
responde a requisições não autenticadas em /mcp/oauth com 401 e WWW-Authenticate: Bearer resource_metadata="...", que é como os clientes descobrem o fluxo;
valida cada token contra a API uma vez por sessão (cache de cinco minutos) e aplica o scope do token por ferramenta: ferramentas somente leitura precisam de read, ferramentas destrutivas precisam de admin, todo o resto precisa de write. search, fetch, ethora-help, ethora-status e ethora-doctor não precisam de escopo. Tokens sem declaração de escopo (chaves de API) recebem acesso total;
oculta as ferramentas de identidade (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 o token já define quem você é.

O servidor de autorização em si faz parte do backend Ethora: <issuer>/.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize (uma página de consentimento com login, criação de conta e login Google), /oauth/token, /oauth/revoke e /oauth/userinfo. Os usuários veem e desconectam concessões OAuth em Conta, Assistentes de IA, Apps de IA conectados. Quando ETHORA_MCP_AUTH_ISSUER não está definido, ambas as rotas OAuth retornam 404 e a descoberta as omite.

Escopos de identidade. Alguns diretórios (ChatGPT) exigem a superfície mínima OpenID Connect sobre OAuth 2.1: os escopos openid e email e um endpoint userinfo que retorna sub, email e email_verified. Esses escopos não concedem acesso a apps ou dados; eles apenas permitem que o cliente veja quem fez login, e a página de consentimento diz isso em palavras simples. Não há tokens de ID ou JWKS, porque nada os consome.

A confirmação de e-mail é opcional. A Ethora nunca bloqueia o cadastro ou o painel por endereço não confirmado. Quando um cliente solicita os escopos de identidade e o endereço da conta ainda não está confirmado, a página de consentimento adiciona uma etapa: enviar o link de confirmação, continuar após confirmar ou continuar sem compartilhar o endereço (os escopos de identidade são removidos da concessão e todo o resto prossegue). Logins Google chegam confirmados e pulam a etapa. A mesma confirmação pode ser enviada de Conta, Assistentes de IA no app web.

O que os agentes podem fazer

A jornada de ponta a ponta que um novo usuário normalmente solicita, com as ferramentas em ordem:

ethora-user-register (ou ethora-user-login) para obter uma sessão autenticada e uma chave de API.
ethora-app-create { displayName } e depois ethora-app-select { appId } para tornar o novo app atual.
ethora-chat-create { title } para criar uma sala de grupo. O resultado contém o JID da sala ${appId}_${chatId}; toda ferramenta de sala aceita o JID ou o chatId simples.
ethora-agent-create { name, prompt, ... } para criar uma persona de agente de IA nesse app.
ethora-agent-invite { agentIdOrAddress, chatJid } para colocar o agente na sala. Uma instância de bot é gerada ao vivo, sem necessidade de reinício.
ethora-message-send { text, roomJid, waitForReplySec: 45 } para publicar uma mensagem e aguardar a resposta do agente, retornada como replies. ethora-chat-history lê a sala depois.
ethora-agent-activate { agentId, chatJid } para tornar esse agente o respondedor padrão do app, e depois ethora-widget-snippet-get para a tag <script> que coloca o widget de chat de IA em um site.

ethora-help { goal } retorna isso e as outras receitas (user-login, broadcast, sources-ingest, files-upload, bot-manage, chat-test, widget, b2b-bootstrap-ai) com as chamadas preenchidas para o estado atual, e ethora-recipe-run as executa.

Convenções do primeiro minuto

Toda ferramenta de criação responde da mesma forma. ethora-app-create, ethora-chat-create, ethora-agent-create retornam o objeto bruto da API mais created (kind, id, name e jid ou address quando relevante) e next, duas a quatro chamadas sugeridas com argumentos preenchidos. ethora-app-create também retorna dashboardUrl, o app no painel web.
ethora-help { goal } tem uma receita para cada tarefa principal: new-app, in-app-chat, multi-agent-room, widget, chat-test, além dos objetivos de integração de servidor. Cada uma retorna as chamadas em ordem com argumentos para copiar.
Quem falou. ethora-message-send responde e as linhas de ethora-chat-history carregam senderName e senderKind (human, agent, app), então uma sala multiagente é lida como "Freud: ..., Jung: ..." em vez de ids de instância.
A busca entende a intenção. search mapeia as frases que as pessoas usam ("adicionar chat ao meu app React", "vários agentes conversando entre si", "webhook quando uma mensagem chega") para os documentos que as respondem, e doc:not-available diz claramente o que não é exposto via MCP e onde isso vive em vez disso. Documentos inteiros podem ser buscados pelo id simples (doc:recipes, doc:chat-component-quickstart, doc:sdk-backend-quickstart, doc:auth-map).

Documentação dentro do servidor

instructions no resultado de inicialização informam ao assistente como a identidade funciona no ponto de entrada pelo qual ele se conectou: o endpoint aberto explica login e registro, sessões por URL pessoal e Bearer são informadas de que já estão autenticadas e nunca devem pedir senha ou chave, sessões OAuth o mesmo, além de como reagir a INSUFFICIENT_SCOPE.
search { query } e fetch { id } (a convenção do conector ChatGPT) buscam em um corpus em memória: o mapa de autenticação, guias de início rápido, receitas, um guia de introdução hospedado, um guia de chaves de API e uma entrada de referência por ferramenta com suas entradas. Funcionam sem autenticação.
Recursos ethora://docs/auth-map, ethora://docs/chat-component/quickstart, ethora://docs/sdk-backend/quickstart, ethora://docs/recipes e prompts ethora-auth-map, ethora-vite-quickstart, ethora-nextjs-quickstart, ethora-backend-sdk-quickstart, ethora-recipes, ethora-agents-quickstart.

Grupos de ferramentas

Uma sessão lista apenas o grupo core no início: 24 ferramentas cobrindo toda a jornada "entrar, criar um app, adicionar salas e mensagens, criar e ativar um agente, dar a ele uma base de conhecimento, obter o widget", uma variante por operação. Os outros grupos são registrados mas ocultos, o que mantém tools/list em cerca de 40 KB em vez de 120 KB e dá aos assistentes uma lista curta para escolher.

Três formas de obter mais:

ethora-tools-enable { group } habilita um grupo para a sessão (ou { group: "all" }); o servidor envia tools/list_changed e o cliente atualiza. Sem argumentos, retorna o catálogo com contagens.
Chamar uma ferramenta oculta pelo nome habilita seu grupo e a executa, então um nome aprendido da documentação ou de uma sessão anterior nunca é recusado.
?tools=all na URL do endpoint (hospedado) ou ETHORA_MCP_TOOLS=all (stdio) lista tudo antecipadamente.

search e fetch também descrevem ferramentas ocultas; cada documento de ferramenta nomeia seu grupo, e doc:tool-groups é o catálogo. Variantes legadas e assíncronas carregam uma primeira linha nomeando o irmão preferido.

Grupo	O que cobre	Ferramentas
`core` (listado por padrão)	Entrar ou registrar, criar um app, adicionar salas e mensagens, criar e ativar um agente de IA, dar a ele uma base de conhecimento, obter o widget do site. Sempre 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 e revogar chaves de API, revelar credenciais de um app, emitir e rotacionar tokens de app.	`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, receitas e alternância do modo de autenticação da sessão (token de app, token B2B) para integrações de servidor.	`ethora-doctor`, `ethora-recipe-run`, `ethora-session-configure`, `ethora-auth-mode-set`, `ethora-auth-mode-set`, `ethora-auth-mode-set`
`apps-admin`	Excluir, exportar e importar apps inteiros; inspecionar salas padrão.	`ethora-app-delete`, `ethora-app-export`, `ethora-app-import`, `ethora-app-rooms-list`, `ethora-app-rooms-list`
`rooms`	Excluir salas, transmitir para muitas salas, pesquisar mensagens, ler contexto de mensagem e contagens de não lidas.	`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`	Inspecionar, clonar, excluir, exportar e importar agentes; editar a alma e a visibilidade de um 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`	Manutenção da base de conhecimento: trabalhos assíncronos de rastreamento e reindexação, listar e marcar sites e documentos, excluir URLs e 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`	Criar usuários em lote e enviar, buscar ou excluir arquivos.	`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`	O bot por app de apps criados no painel antes do framework de agentes, e as ferramentas de documento pré-v2. Prefira as ferramentas de agentes e fontes para qualquer coisa nova.	`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`	Provisionamento servidor a servidor com token B2B, além de geradores de código e configuração para integrações.	`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 da carteira e transferência ERC-20. Apenas local (stdio); nunca oferecido no servidor hospedado.	`ethora-wallet-balance-get`, `ethora-wallet-erc20-transfer`

As ferramentas de exclusão de app e exclusão em lote são registradas apenas quando ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true (o deploy monoserver define isso; o padrão stdio é desligado). Ferramentas de alias (ethora.b2b.*, ethora-bot-message-send, ethora-bot-history) estão desligadas por padrão (ETHORA_MCP_ENABLE_ALIASES=true para expô-las); as ferramentas canônicas cobrem o mesmo terreno.

Widget do site

ethora-widget-snippet-get retorna a tag para o widget de chat de IA incorporável:

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

O widget responde com o bot ativo do app (defaultBotInstanceId). Em um app criado pela API, execute ethora-agent-create, ethora-chat-create, ethora-agent-invite e ethora-agent-activate { agentId, chatJid } primeiro; a ferramenta lista esses pré-requisitos e ethora-help { goal: "widget" } percorre todos eles. A ativação ocorre na autenticação do usuário definindo a instância de bot padrão do app (o que o menu suspenso de IA do Widget do administrador faz). Até que um bot esteja ativo, o endpoint de sessão do widget responde AI_BOT_NOT_CONFIGURED. ethora-chat-component-app-generate produz um React App.tsx para @ethora/chat-component em vez disso.

Configuração

Variáveis de ambiente (stdio e hospedado)

Variável	Significado
`ETHORA_API_URL`	URL completa da API, ex.: `https://api.chat.ethora.com/v1` (padrão). Em um servidor hospedado, é fixa para todas as sessões
`ETHORA_BASE_URL`	Alternativa somente para host a `ETHORA_API_URL`; `/v1` é anexado
`ETHORA_APP_JWT`	JWT do app usado apenas por login e registro (`ETHORA_APP_TOKEN` é um alias legado)
`ETHORA_APP_DOMAIN_NAME`	`domainName` base do app; quando `ETHORA_APP_JWT` está vazio, o servidor busca o JWT do app de `GET /v1/apps/get-config?domainName=...` na inicialização
`ETHORA_B2B_TOKEN`	Token de servidor B2B para rotas de ator de locatário `x-custom-token`
`ETHORA_MCP_TOOLS`	`all` lista todas as ferramentas desde o início em vez do grupo principal (stdio; hospedado usa `?tools=all` na URL)
`ETHORA_MCP_ENABLE_DANGEROUS_TOOLS`	`true` registra ferramentas de exclusão de app, transferência de carteira e exclusão em lote (padrão desligado)
`ETHORA_MCP_OPENAI_APPS_CHALLENGE`	Somente hospedado. Token emitido pelo portal de apps OpenAI para verificação de domínio; servido literalmente em `/.well-known/openai-apps-challenge` (404 quando não definido)
`ETHORA_MCP_ENABLE_ALIASES`	`true` expõe as ferramentas de alias com namespace de ponto (padrão desligado)

Somente modo hospedado

Variável	Significado
`ETHORA_MCP_TRANSPORT`	`stdio` (padrão) ou `http`; `--http` na linha de comando faz o mesmo
`ETHORA_MCP_HTTP_HOST`, `ETHORA_MCP_HTTP_PORT`	Endereço de bind, padrão `127.0.0.1:3030`; coloque nginx na frente
`ETHORA_MCP_PUBLIC_URL`	URL base pública anunciada na descoberta e usada para `connectorUrl`, ex.: `https://mcp.chat.ethora.com/mcp`
`ETHORA_MCP_TRUST_PROXY`	`true` obtém o IP do cliente de `X-Forwarded-For`; ele é encaminhado à API para que limites por IP se apliquem por chamador
`ETHORA_MCP_SESSION_TTL_MS`	Despejo de sessão ociosa, padrão 4 horas
`ETHORA_MCP_AUTH_ISSUER`	URL pública do servidor de autorização OAuth (o host da API Ethora); habilita `/mcp/oauth`
`ETHORA_MCP_WIDGET_URL`	URL base do widget de chat de IA hospedado (`<url>/assistant.js`) para `ethora-widget-snippet-get`
`ETHORA_MCP_PUBLIC_API_URL`	Base da API pública que os navegadores podem alcançar, emitida como `data-api-base`; recai para `ETHORA_MCP_AUTH_ISSUER`, depois um `ETHORA_API_URL` não loopback

Um arquivo .env no diretório de trabalho é carregado na inicialização; variáveis de ambiente reais vencem. Credenciais também podem ser definidas por sessão com ethora-session-configure (apenas em memória; em um servidor hospedado, apiUrl não pode ser alterado).

Endpoints (hospedado)

Caminho	Propósito
`POST\|GET\|DELETE /mcp`	Endpoint MCP HTTP transmissível, aberto
`POST\|GET\|DELETE /mcp/k/<api-key>`	O mesmo, autenticado pela chave no caminho
`POST\|GET\|DELETE /mcp/oauth`	O mesmo, token Bearer exigido, escopos aplicados
`GET /healthz`	`{ ok, sessions, version, appJwtReady, oauth }`
`GET /.well-known/mcp` e `GET /`	JSON de descoberta: endpoint, transporte, opções de autenticação, metadados OAuth
`GET /.well-known/oauth-protected-resource[/mcp/oauth]`	Metadados de recurso protegido RFC 9728

Envelope de resposta

Cada ferramenta retorna texto JSON em uma forma: sucesso { ok: true, ts, meta, data }, falha { ok: false, ts, meta, error } onde error carrega code (o código próprio da API quando tem um), message, httpStatus, requestId e um hint de uma linha.

Uso com clientes stdio

Cada cliente stdio executa npx -y @ethora/mcp-server; passe credenciais como variáveis de ambiente (preferido) ou chame ethora-session-configure para um teste local rápido (seus argumentos acabam no transcript). Para o modo hospedado, use os botões de um clique no topo deste README, ou o formulário de URL no quickstart. Botões de um clique para o pacote stdio:

Cursor

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

VS Code (e modo agente do GitHub Copilot)

.vscode/mcp.json (observe que a chave é 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

Adicione --scope user para disponibilizá-lo em todos os projetos; verifique com claude mcp list.

Claude Desktop

Configurações, Desenvolvedor, Editar Config (claude_desktop_config.json):

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

Gemini CLI, Windsurf, Cline

Mesmo bloco mcpServers acima em ~/.gemini/settings.json, ~/.codeium/windsurf/mcp_config.json ou cline_mcp_settings.json.

Codex CLI

~/.codex/config.toml (a tabela é mcp_servers com um sublinhado):

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

Contêiner

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

Adicione -e ETHORA_MCP_TRANSPORT=http -e ETHORA_MCP_HTTP_HOST=0.0.0.0 -p 3030:3030 para executar o modo hospedado em um contêiner.

Provisionamento B2B (integrações de servidor)

Com ETHORA_B2B_TOKEN configurado, ethora-auth-mode-set alterna a sessão para autenticação de ator de locatário e ethora-b2b-app-bootstrap-ai cria um app, indexa fontes (crawlUrl, docs[] como base64) e configura seu bot em uma chamada, com llmProvider e llmModel opcionais. ethora-b2b-app-provision adiciona tokens de app e salas padrão. ethora-user-batch-create mais ethora-user-batch-job-wait provisionam usuários assincronamente e ethora-broadcast-send mais ethora-broadcast-job-wait enviam uma mensagem para muitas salas. ethora-b2b-runbook-generate imprime a ordem de chamadas para sua própria automação.

Solução de problemas

Sintoma	Significado e correção
`TOKEN_MISSING` (401)	A sessão não tem token de usuário. Chame `ethora-user-login` ou `ethora-user-register`, ou conecte com um cabeçalho Bearer ou URL pessoal
`REFRESH_RECORD_NOT_FOUND` (401)	A chave de API ou token foi revogado. Crie uma nova chave
`INSUFFICIENT_SCOPE` (403) em `/mcp/oauth`	A concessão OAuth não tem o escopo que a ferramenta precisa (`read`, `write` ou `admin`). Reconecte e aprove o escopo mais amplo
`This tool requires app-token auth` ou `AUTH_USER_REQUIRED`	Modo de autenticação errado. No servidor hospedado, permaneça no modo de usuário (`ethora-auth-mode-set`); o modo de token de app é apenas para `/v2/bot` e rotas de widget
`AI_BOT_NOT_CONFIGURED` do widget	Nenhum bot ativo no app. Execute as etapas do agente, convite e `ethora-agent-activate`, depois recarregue a página
`BOT_NOT_INITIALIZED` (422) de `ethora-bot-*`	O app não tem bot legado por app; use as ferramentas de agentes em vez disso
`AGENT_NOT_FOUND` ou `APP_NOT_FOUND` (404)	ID errado ou o app não foi selecionado; `ethora-app-select` primeiro, ou passe `appId`
`Not Acceptable` (406) de `/mcp`	O cliente deve aceitar tanto `application/json` quanto `text/event-stream`
Página de consentimento diz `Social sign-in failed (auth/...)`	O código Firebase entre parênteses nomeia a causa (o console do navegador tem o erro completo). `auth/popup-blocked`: permita popups para o host da API. Uma mensagem sem código foi corrigida no backend em 2026-09-17; atualize se você auto-hospedar
Cliente não consegue conectar (stdio)	Execute `npx -y @ethora/mcp-server` em um terminal e verifique Node 18 ou mais novo
Servidor hospedado não responde	`GET /healthz`; `appJwtReady: false` significa que o bootstrap do JWT do app base falhou (verifique `ETHORA_APP_DOMAIN_NAME` e `ETHORA_API_URL`)

Feedback

ethora-feedback-submit envia um relatório (bug, unexpected, feature, docs, other) para a equipe Ethora de dentro de uma sessão. O objetivo de fazer isso via MCP em vez de um formulário web é o contexto: as últimas falhas de ferramentas da sessão acompanham o relatório - nome da ferramenta, código de erro e a API requestId - para que um relatório possa ser associado à entrada de log do lado do servidor em vez de ser redigitado de memória. Defina includeRecentErrors: false quando o relatório não estiver relacionado a uma falha.

Funciona esteja a sessão autenticada ou não, porque o relator que mais precisamos ouvir é aquele cujo cadastro ou credencial foi o que quebrou; um relatório autenticado é atribuído a essa conta, e um anônimo pode carregar um email para uma resposta. Também está isento da aplicação de escopo OAuth, então uma concessão somente leitura ainda pode relatar um problema.

Chaves em formato de credencial no contexto anexado são redigidas antes do envio. Isso é baseado em chave, então não pode capturar uma credencial colada no texto livre message: a descrição da ferramenta diz ao modelo para não colocar segredos ou dados pessoais do usuário final ali.

A entrega é configurada no lado da API (FEEDBACK_EMAIL_TO, FEEDBACK_SLACK_WEBHOOK_URL, FEEDBACK_RETENTION_DAYS); o servidor MCP apenas submete.

Atribuição de uso

Chamadas de API de saída carregam X-Ethora-Client: mcp/<version> e, durante a duração de uma chamada de ferramenta, X-Ethora-Tool: <tool-name>. A API registra esses no log de solicitações como client e source: mcp:<tool>, que é como o tráfego MCP é separado do aplicativo web e contado por ferramenta. Os endpoints públicos não autenticados (/ping, /apps/get-config) ficam sem atribuição.

Notas de segurança

Credenciais são redigidas dos resultados das ferramentas. appSecret, tenantSecret, appToken, senhas e chaves semelhantes retornam como [redacted] de todas as ferramentas (os resultados entram no contexto do modelo e nos logs do cliente). ethora-app-credentials-reveal { appId, confirm: true } revela o appToken de um aplicativo de propósito e precisa do escopo admin via OAuth; o App Secret só é mostrado na aba de API do painel web. As ferramentas de login, registro e cunhagem de api-key / app-token ainda retornam sua credencial uma vez por design.
Chaves de API e URLs pessoais agem como o usuário até serem revogadas. Mantenha-as no cofre de segredos do seu cliente, nunca em configuração compartilhada ou capturas de tela, e revogue sob suspeita.
O servidor nunca registra URLs de solicitação ou tokens. Mantenha o log de acesso do seu proxy reverso livre de caminhos de solicitação para o host MCP (o template nginx do monoserver faz isso).
Qualquer coisa retornada por uma ferramenta é visível para o modelo e armazenada na transcrição da conversa; o servidor instrui assistentes a não imprimir chaves ou senhas e a confirmar ferramentas destrutivas com o usuário.
Este repositório executa varreduras de segredos e SAST somente de relatório (gitleaks, semgrep) em pushes e PRs.

Desenvolvimento

Números de versão

As versões são baseadas em calendário: YY.M.patch, onde YY.M é o ano e mês em que o lançamento sai (26.9.5 é o quinto lançamento de setembro de 2026, 26.10.0 o primeiro de outubro) e patch conta lançamentos dentro do mês. Sem zero à esquerda no mês, então 26.10 ordena depois de 26.9 sob semver. Mudanças que quebram compatibilidade não aumentam a versão principal; elas recebem o próximo patch e uma entrada no changelog, e nomes de ferramentas anteriores permanecem chamáveis como aliases. npm run sync-version recusa qualquer outra forma ou qualquer mês diferente do atual (ETHORA_VERSION_MONTH=YY.M substitui de propósito), e o fluxo de publicação o executa. 27.0.0 e 27.1.0, publicados em 2026-09-24 contra esta regra, estão obsoletos; 26.9.5 é o mesmo código.

Nomenclatura de ferramentas

Desde 27.0, toda ferramenta listada segue uma regra: ethora-<resource>-<verb>[-<qualifier>].

recurso é um substantivo singular, uma ou duas palavras: app, agent, chat, message, broadcast, source-site, source-doc, user, file, bot, api-key, app-token, widget, wallet, session, auth-mode, recipe, tools.
verbo é a última palavra: create, list, get, update, delete, send, set, run, reveal, upload, crawl, reindex, start, wait, enable, disable, generate.
um qualificador só segue o verbo: -wait (forma bloqueante de um trabalho assíncrono), -batch, -legacy, -b2b.
sem sufixos de versão de API: -v2 desapareceu de todos os nomes. search e fetch mantêm seus nomes por convenção do conector ChatGPT.

Todo nome anterior ainda funciona. Nomes antigos são aliases: nunca listados por tools/list, mas uma chamada para um é reescrita para a ferramenta canônica (com um argumento predefinido onde três ou duas ferramentas se tornaram uma, como ethora-auth-use-app se tornando ethora-auth-mode-set { mode: "app" }), então configurações publicadas, receitas e conversas salvas continuam funcionando. Resultados e atribuição de uso nomeiam a ferramenta canônica. O mapeamento completo está em a tabela de aliases no final deste arquivo e em src/toolNames.ts, que o conjunto de testes verifica contra o registro.

Repositórios relacionados

ethora-chat-component: o componente de chat React usado em widgets e aplicativos autônomos
ethora-monoserver: automação de implantação que envia este servidor como um serviço opcional (repositório privado, disponível para clientes empresariais)
ethora-wp-plugin: integração WordPress
rag_demos: exemplos de assistente de IA RAG

Pontuação de qualidade e manutenção

Inspecionado independentemente por Glama, que constrói o servidor, cataloga suas ferramentas e avalia a qualidade da definição de ferramentas e a atividade de manutenção.

Nomes de ferramentas anteriores

Nomes usados antes de 27.0 e a ferramenta para a qual cada um agora resolve. Todos permanecem chamáveis.

Nome anterior	Ferramenta 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` com `{"mode": "app"}`
`ethora-auth-use-b2b`	`ethora-auth-mode-set` com `{"mode": "b2b"}`
`ethora-auth-use-user`	`ethora-auth-mode-set` com `{"mode": "user"}`
`ethora.b2b.auth.use`	`ethora-auth-mode-set` com `{"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`

Licença

Veja LICENSE.