Ethora MCP CLI

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

GitHub
6
Experimente este MCPPatrocinado

Documentação

Ethora MCP Server (Model Context Protocol)

npm Node License

Add to Cursor Install in VS Code Install in VS Code Insiders

Instalação com um clique para Cursor e VS Code (botões acima). Para Claude Code, Claude Desktop, GitHub Copilot, Gemini CLI, Codex CLI, Windsurf e Cline, consulte Usando com clientes MCP abaixo.

Um CLI/servidor MCP (Model Context Protocol) que conecta clientes MCP populares à plataforma Ethora — uma plataforma de chat e mensagens de código aberto com um framework integrado de agente de IA / chatbot. Ele roda localmente na máquina do desenvolvedor via stdio, em vez de um serviço Ethora hospedado.
Use-o a partir do Cursor, VS Code MCP, Claude Desktop ou Windsurf/Cline para gerenciar aplicativos e salas de chat, transmitir mensagens, implantar agentes de IA / chatbots com fontes RAG e automatizar fluxos de provisionamento B2B. (Ferramentas de carteira ERC-20 também estão incluídas — veja a lista de ferramentas abaixo.)

Parte do ecossistema Ethora SDK — veja todos os SDKs, ferramentas e aplicativos de exemplo. Acompanhe as atualizações entre SDKs nas Notas de versão.

✨ O que você obtém

  • Fale com a plataforma Ethora diretamente do seu IDE ou cliente de agente de IA (Cursor, VS Code MCP, Claude Desktop, Windsurf / Cline).
  • Fluxos de autenticação de usuário (login/registro, arquivos, endpoints de proprietário/admin) e fluxos B2B / app-token (provisionamento de tenant, jobs de broadcast, lotes assíncronos de usuários, configuração de bot de IA).
  • Receitas, prompts e geradores integrados para os fluxos de trabalho Ethora mais comuns (configuração de componente de chat Vite/Next, bootstrap B2B, habilitação de bot de IA, fontes RAG).
  • Envelope de resposta padrão de ferramenta ({ ok, ts, meta, data | error }) para que o código do agente possa avaliar sucesso/falha de forma consistente.

🚦 Só testando? (início rápido de 60 segundos)

Não leia os modos de autenticação ainda. Depois que o servidor estiver conectado no seu cliente, peça ao seu agente para executar, em ordem:

  1. ethora-doctor — confirma que o servidor está ativo e consegue acessar a API Ethora. Nenhuma credencial é necessária.
  2. ethora-configure com seu appJwt → ethora-auth-use-user → ethora-user-login com um e-mail + senha.
  3. ethora-app-list — pronto; isso lista seus aplicativos.

Esse é o caminho do desenvolvedor local. Precisa de automação no lado do servidor? Vá para modo B2B. Perdeu-se em algum ponto? Chame ethora-help — ele lê seu estado atual e informa a próxima chamada.

🔐 Dois modos de uso típicos

1) Modo de autenticação de usuário

Ideal para:

  • desenvolvedores testando Ethora localmente
  • administradores de tenant / proprietários de aplicativos usando MCP manualmente
  • fluxos que começam com ethora-user-login

Como funciona:

  • configure ETHORA_APP_JWT uma vez para o bootstrap de login/registro
  • alterne para ethora-auth-use-user
  • chame ethora-user-login
  • use ferramentas de autenticação de usuário, como arquivos e endpoints legados de proprietário/admin

2) Modo B2B

Ideal para:

  • integrações permanentes de backend
  • fluxos de provisionamento de parceiros
  • agentes autônomos operando Ethora sem uma sessão de usuário humano

Como funciona:

  • configure ETHORA_B2B_TOKEN
  • alterne para ethora-auth-use-b2b para rotas /v2/apps/:appId/... explícitas de ator de tenant
  • opcionalmente, alterne para ethora-auth-use-app após ethora-app-select quando quiser rotas de conveniência com escopo de aplicativo alimentadas por appToken

Regra prática:

  • o primeiro uso local geralmente começa com User Auth
  • automação repetível geralmente começa com B2B e depois costuma migrar para o modo app-token para um aplicativo selecionado

Prompts e recursos (P2: documentação voltada ao desenvolvedor)

  • Recursos (documentos carregáveis no contexto)
    • ethora://docs/auth-map — appJwt vs appToken vs b2bToken
    • ethora://docs/chat-component/quickstart — início rápido Vite/Next + substituição de tokens de demonstração
    • ethora://docs/sdk-backend/quickstart — início rápido de integração de backend
    • ethora://docs/recipes — sequências comuns de ferramentas (broadcast/sources/files/bot)
  • Prompts
    • ethora-auth-map
    • ethora-vite-quickstart
    • ethora-nextjs-quickstart
    • ethora-backend-sdk-quickstart
    • ethora-recipes

Geradores (sem shell, sem gravação de arquivos)

  • ethora-generate-chat-component-app-tsx — snippet App.tsx pronto para colar para @ethora/chat-component
  • ethora-generate-env-examples — modelos .env.example para:
    • componente de chat de frontend
    • integração de SDK de backend
    • uso de MCP (ETHORA_API_URL, ETHORA_APP_JWT, ETHORA_B2B_TOKEN)
  • ethora-generate-b2b-bootstrap-runbook — runbook mínimo de "chame estas ferramentas MCP em ordem" para bootstrap B2B

Dica: para listar receitas executáveis sem chamar ethora-help, chame ethora-run-recipe com goal: "auto" e omita recipeId.

  • Sessão / Configuração

    • ethora-configure — define a URL da API mais App JWT / token B2B / appToken para esta sessão MCP
    • ethora-status — mostra a URL da API configurada, o modo de autenticação ativo e quais credenciais estão presentes
    • ethora-help — ajuda orientada a tarefas (próximas chamadas recomendadas + "receitas de um clique" com base no estado atual)
    • ethora-run-recipe — executa uma receita integrada por id (etapas sequenciais; sem shell, sem gravação de arquivos)
    • ethora-doctor — valida a configuração + faz ping na API Ethora configurada para uso de usuário e B2B
    • ethora-app-select — seleciona o appId atual e opcionalmente define o appToken
    • ethora-auth-use-app — alterna para o modo de autenticação app-token para operações com escopo de aplicativo
    • ethora-auth-use-user — alterna para o modo de autenticação de sessão de usuário
    • ethora-auth-use-b2b — alterna para o modo de autenticação B2B x-custom-token de ator de tenant

  • Chats (v2)

    • ethora-chats-broadcast-v2 — enfileira job de broadcast usando autenticação app-token ou B2B + appId explícito
    • ethora-chats-broadcast-job-v2 — obtém status/resultados do job de broadcast usando autenticação app-token ou B2B + appId explícito
    • ethora-wait-broadcast-job-v2 — faz polling do job de broadcast até concluído/falho usando autenticação app-token ou B2B + appId explícito
    • ethora-chats-message-v2 — envia uma mensagem de teste/automação pela superfície de chat do aplicativo (requer autenticação app-token)
    • ethora-chats-history-v2 — lê o histórico persistido de automação/teste para sessões privadas ou em grupo (requer autenticação app-token)

  • Usuários (lote assíncrono v2)

    • ethora-users-batch-create-v2 — cria job de lote assíncrono de usuários (requer autenticação B2B)
    • ethora-users-batch-job-v2 — obtém status/resultados do job de lote de usuários (requer autenticação B2B)
    • ethora-wait-users-batch-job-v2 — faz polling do job de lote de usuários até concluído/falho (requer autenticação B2B)

  • Arquivos (v2)

  • Bot / Agente (v2)

    • ethora-bot-get-v2 — obtém status/configurações do bot usando autenticação app-token ou B2B + appId explícito

    • ethora-bot-update-v2 — atualiza configurações do bot usando autenticação app-token ou B2B + appId explícito

    • ethora-bot-enable-v2 — habilita o bot usando autenticação app-token ou B2B + appId explícito

    • ethora-bot-disable-v2 — desabilita o bot usando autenticação app-token ou B2B + appId explícito

    • ethora-bot-widget-v2 — obtém configuração de widget/embed e metadados da URL pública do widget (autenticação app-token)

    • ethora-agents-list-v2 — lista agentes salvos reutilizáveis para o proprietário atual do aplicativo (autenticação app-token)

    • ethora-agents-get-v2 — obtém um agente salvo reutilizável (autenticação app-token)

    • ethora-agents-create-v2 — cria um agente salvo reutilizável (autenticação app-token)

    • ethora-agents-update-v2 — atualiza um agente salvo reutilizável (autenticação app-token)

    • ethora-agents-clone-v2 — clona um agente salvo reutilizável (autenticação app-token)

    • ethora-agents-activate-v2 — vincula um agente salvo como o bot ativo para o aplicativo selecionado (autenticação app-token)

    • ethora-bot-message-v2 — alias de compatibilidade para ethora-chats-message-v2

    • ethora-bot-history-v2 — alias de compatibilidade para ethora-chats-history-v2

    • ethora-files-upload-v2 — envia arquivos (requer autenticação de usuário)

    • ethora-files-get-v2 — lista/obtém arquivos (requer autenticação de usuário)

    • ethora-files-delete-v2 — exclui arquivo por id (requer autenticação de usuário)

  • Fontes

    • ethora-sources-site-crawl — rastreia uma URL (requer autenticação de usuário)
    • ethora-sources-site-reindex — reindexa URL por urlId (requer autenticação de usuário)
    • ethora-sources-site-delete-url — exclui por URL (requer autenticação de usuário)
    • ethora-sources-site-delete-url-v2 — exclui URLs em lote (requer autenticação de usuário)
    • ethora-sources-docs-upload — envia documentos para ingestão (requer autenticação de usuário)
    • ethora-sources-docs-delete — exclui documento ingerido por id (requer autenticação de usuário)
    • ethora-sources-site-crawl-v2 — rastreia uma URL usando autenticação app-token ou B2B + appId explícito
    • ethora-sources-site-reindex-v2 — reindexa URL por urlId usando autenticação app-token ou B2B + appId explícito
    • ethora-sources-site-crawl-v2-wait — auxiliar de chamada única com timeout longo para rastreamento (autenticação app-token)
    • ethora-sources-site-reindex-v2-wait — auxiliar de chamada única com timeout longo para reindexação (autenticação app-token)
    • ethora-sources-site-list-v2 — lista fontes de site rastreadas e tags atuais usando autenticação app-token ou B2B + appId explícito
    • ethora-sources-site-tags-update-v2 — define/atualiza tags para uma fonte de site rastreada usando autenticação app-token ou B2B + appId explícito
    • ethora-sources-site-delete-url-v2 — exclui uma URL rastreada por URL usando autenticação app-token ou B2B + appId explícito
    • ethora-sources-site-delete-url-v2-batch — exclui em lote registros de fonte rastreada por id usando autenticação app-token ou B2B + appId explícito
    • ethora-sources-docs-upload-v2 — envia documentos para ingestão usando autenticação app-token ou B2B + appId explícito
    • ethora-sources-docs-list-v2 — lista documentos indexados e tags atuais usando autenticação app-token ou B2B + appId explícito
    • ethora-sources-docs-tags-update-v2 — define/atualiza tags para um documento indexado usando autenticação app-token ou B2B + appId explícito
    • ethora-sources-docs-delete-v2 — exclui documento por id usando autenticação app-token ou B2B + appId explícito

  • Autenticação e contas

    • ethora-user-login — faz login do usuário (e-mail + senha)
    • ethora-user-register — registra usuário (e-mail + nome/sobrenome)

  • Aplicativos

    • ethora-app-create — cria aplicativo
    • ethora-app-update — atualiza aplicativo
    • ethora-app-delete — exclui aplicativo
    • ethora-app-list — lista aplicativos
    • ethora-b2b-app-create — cria aplicativo usando autenticação B2B (x-custom-token)
    • ethora-b2b-app-bootstrap-ai — cria aplicativo → indexa fontes → configura/habilita bot, incluindo seleção de LLM em tempo de execução (automação B2B)
    • ethora-app-tokens-list-v2 — lista metadados de token de aplicativo (autenticação B2B)
    • ethora-app-tokens-create-v2 — cria novo token de aplicativo (retornado uma única vez) (autenticação B2B)
    • ethora-app-tokens-rotate-v2 — rotaciona token (revoga o antigo, retorna o novo uma única vez) (autenticação B2B)
    • ethora-app-tokens-revoke-v2 — revoga token por tokenId (idempotente) (autenticação B2B)
    • ethora-b2b-app-provision — cria aplicativo + cria tokens + provisiona salas + configura bot, incluindo seleção de LLM em tempo de execução (orquestrador B2B)

  • Chat e salas

    • ethora-app-get-default-rooms — lista salas padrão
    • ethora-app-get-default-rooms-with-app-id — salas para um determinado aplicativo
    • ethora-app-create-chat — cria chat para aplicativo
    • ethora-app-delete-chat — exclui chat

  • Carteira

    • ethora-wallet-get-balance — obtém saldo
    • ethora-wallet-erc20-transfer — envia tokens ERC-20

Os nomes de ferramentas acima refletem as áreas funcionais expostas pelo servidor. Seus nomes exatos de ferramentas podem variar ligeiramente conforme a versão; execute o "list tools" do cliente para confirmar.

settings login

📦 Instalação / Execução

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

  • Node.js instalado no seu sistema (versão recomendada 18.x ou superior).

Instalação

O servidor é distribuído como um pacote npm e normalmente é iniciado por clientes MCP via npx:

npx -y @ethora/mcp-server

Nenhuma instalação global é necessária.

🔐 Configuração (variáveis de ambiente)

Este servidor MCP suporta tanto o fluxo local de autenticação de usuário quanto o fluxo B2B no lado do servidor.

Valores principais:

  • URL da API Ethora (para onde enviar solicitações)
  • Ethora App JWT (usado apenas para o bootstrap de login/registro no modo de autenticação de usuário)
  • Ethora B2B Token (usado para fluxos servidor-a-servidor de ator de tenant)

Você pode fornecê-los de duas formas:

  • via variáveis de ambiente, ou
  • em tempo de execução via a ferramenta ethora-configure (em memória; é redefinida quando o processo MCP reinicia)

Variáveis de ambiente suportadas

  • ETHORA_API_URL: URL completa da API (exemplo: https://api.chat.ethora.com/v1, http://localhost:8080/v1)
  • ETHORA_BASE_URL: URL base do host (exemplo: https://api.chat.ethora.com, http://localhost:8080)
    Se fornecido, o servidor usará por padrão .../v1.
  • ETHORA_APP_JWT: string JWT do App, geralmente começando com JWT ...
  • ETHORA_B2B_TOKEN: token de servidor B2B para autenticação x-custom-token (JWT com type=server)
  • ETHORA_MCP_ENABLE_DANGEROUS_TOOLS: habilita ferramentas destrutivas (padrão: desabilitado). Defina como true para expor:
    • ferramentas de exclusão de app
    • ferramentas de transferência de carteira
    • ferramentas de exclusão em massa

Segurança: nunca commite JWTs de App, tokens B2B ou appTokens no git. Configure-os via variáveis de ambiente, no armazenamento de segredos do cliente MCP ou no seu próprio backend.

🧱 Envelope de resposta padrão (ferramentas)

Todas as ferramentas retornam JSON em um envelope consistente:

  • Sucesso: { ok: true, ts, meta, data }
  • Erro: { ok: false, ts, meta, error }, onde error inclui:
    • code: string estável (prefira API code, caso contrário inferida)
    • httpStatus: status HTTP quando a falha veio de uma chamada de API
    • requestId: id de requisição/correlação se retornado pela API
    • hint: linha única "o que fazer a seguir"

🚀 Usando com clientes MCP

Cada cliente executa a mesma coisa — npx -y @ethora/mcp-server via stdio. Botões de um clique existem para Cursor e VS Code (no topo deste README). Para os demais, é um bloco de configuração curto ou um comando de uma linha.

Cursor

Use o botão Adicionar ao Cursor acima, ou manualmente: Configurações → MCP → Adicionar novo servidor MCP global:

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

VS Code (e GitHub Copilot)

Use o botão Instalar no VS Code acima, ou adicione um arquivo .vscode/mcp.json (nível de projeto) — observe que a chave é servers:

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

O modo agente do GitHub Copilot no VS Code lê esse mesmo .vscode/mcp.json — sem configuração separada. (Para instalação em nível de usuário, coloque o bloco servers sob "mcp" no seu JSON de Configurações do Usuário.)

Claude Code

Um comando:

claude mcp add ethora -- npx -y @ethora/mcp-server

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

Para pré-configurar credenciais, passe-as como variáveis de ambiente com -e (recomendado em vez da ferramenta ethora-configure — veja a nota abaixo):

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 segredos: prefira variáveis de ambiente (acima) ou o armazenamento de segredos do seu cliente MCP para credenciais. A ferramenta ethora-configure também funciona, mas passa segredos como argumentos de ferramenta, o que significa que eles acabam no transcript da conversa. Use-a para testes locais rápidos, não para tokens que você valoriza.

Claude Desktop

Configurações → Desenvolvedor → Editar Config, abra claude_desktop_config.json:

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

Gemini CLI

Adicione a ~/.gemini/settings.json (global) ou .gemini/settings.json (por projeto):

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

Codex CLI

Adicione a ~/.codex/config.toml — observe que o nome da tabela é mcp_servers (sublinhado; mcp-servers é ignorado silenciosamente):

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

Windsurf

Configurações → Cascade → Servidores MCP → Ver configuração bruta (~/.codeium/windsurf/mcp_config.json):

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

Cline

Abra o painel de servidores MCP e edite cline_mcp_settings.json:

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

🧪 Teste rápido

Depois que o servidor aparecer como conectado no seu cliente:

  • Execute list tools (comando do cliente) para verificar se as ferramentas Ethora estão disponíveis.
  • Verifique configuração/conectividade: chame ethora-doctor (ou ethora-status)
  • Para um primeiro teste local/manual:
    • chame ethora-configure com apiUrl / appJwt
    • chame ethora-auth-use-user
    • chame ethora-user-login
    • depois tente ethora-app-list ou ethora-wallet-get-balance
  • Para um teste do lado do servidor/B2B:
    • chame ethora-configure com apiUrl / b2bToken
    • chame ethora-auth-use-b2b
    • depois tente ethora-b2b-app-create ou ethora-app-tokens-list-v2

🧭 P1: B2B "criar app → indexar fontes → implantar bot" em uma chamada

Pré-requisitos:

  • Configure ETHORA_API_URL (ou chame ethora-configure)
  • Configure ETHORA_B2B_TOKEN (ou chame ethora-configure com b2bToken)
  • Garanta que seu backend Ethora esteja configurado com URL/segredo do serviço de IA (para ativação do bot)

Fluxo sugerido:

  • Chame ethora-auth-use-b2b
  • Chame ethora-b2b-app-bootstrap-ai com:
    • displayName
    • opcional savedAgentId
    • opcional crawlUrl
    • opcional docs[] (base64)
    • enableBot: true
    • opcional llmProvider
    • opcional llmModel

Ele irá:

  • criar o app (B2B)
  • definir o contexto atual do app (melhor esforço)
  • indexar fontes via /v2/sources/* (autenticação por app-token)
  • configurar e/ou habilitar o bot (melhor esforço)

Exemplos de payloads

Mínimo (apenas criar app):

{
  "displayName": "Acme AI Demo",
  "setAsCurrent": true
}

Criar app + rastrear um site + habilitar bot:

{
  "displayName": "Acme AI Demo",
  "savedAgentId": "6790abc1234567890def1111",
  "crawlUrl": "https://example.com",
  "followLink": true,
  "enableBot": true,
  "botTrigger": "/bot",
  "llmProvider": "openai",
  "llmModel": "gpt-4o-mini"
}

Criar app + enviar 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"
}

Provisionar app + token + salas padrão + configurações do 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 provedor/modelo:

  • Valores comuns são openai e openai-compatible.
  • O provedor/modelo efetivo também deve estar habilitado pelo seu backend Ethora + ambiente do serviço de IA.

🤖 Loop de automação do app

Depois de já ter um app selecionado com autenticação appToken:

  • chame ethora-auth-use-app
  • chame ethora-bot-get-v2 para inspecionar o status atual do bot e as configurações de prompt
  • chame ethora-sources-site-list-v2 e ethora-sources-docs-list-v2 para inspecionar fontes indexadas
  • chame ethora-sources-site-tags-update-v2 ou ethora-sources-docs-tags-update-v2 para organizar a recuperação por tags
  • chame ethora-chats-message-v2 / ethora-chats-history-v2 se o seu backend expõe a superfície de automação de chat no mesmo host da API

Exemplo: aplicar tags de recuperação a uma fonte rastreada

{
  "sourceId": "6790abc1234567890def1234",
  "tags": ["support", "faq", "billing"]
}

Exemplo: aplicar tags de recuperação a um documento indexado

{
  "docId": "6790abc1234567890def1235",
  "tags": ["support", "faq"]
}

🛡️ Notas de segurança

  • Nunca coloque chaves de API fixas em configuração compartilhada. Prefira armazenamentos de segredos no lado do cliente.
  • Use chaves com menor privilégio e considere listas de permissão/limites de taxa no seu backend Ethora.
  • Rotacione credenciais regularmente em uso de produção.

Verificações de segurança em CI (somente relatório)

Este repositório executa verificações somente relatório em pushes/PRs:

  • gitleaks para varredura de segredos
  • semgrep para SAST básico

🧰 Desenvolvimento

Clone e execute localmente:

git clone https://github.com/dappros/ethora-mcp-server.git
cd ethora-mcp-server
npm install
npm run build
npm start

Scripts sugeridos (se não estiverem presentes):

{
  "scripts": {
    "build": "tsc -p .",
    "start": "node dist/index.js",
    "dev": "tsx src/index.ts"
  }
}

❓ Solução de problemas

  • Cliente não consegue conectar: Garanta que npx @ethora/mcp-server execute localmente sem erros. Verifique Node ≥ 18.
  • Erros de autenticação: Verifique se ETHORA_BASE_URL e quaisquer segredos necessários estão definidos no ambiente do cliente.
  • Ferramentas ausentes: Reinicie o cliente MCP e inspecione os logs do servidor para erros de registro.
  • Rede: Confirme o acesso de saída da IDE para o seu host Ethora.

🔗 Repositórios Relacionados

📜 Licença

Veja LICENSE.