{"id":30409738,"url":"https://github.com/dappros/ethora-mcp-server","last_synced_at":"2026-05-28T01:30:36.830Z","repository":{"id":308552363,"uuid":"1033234054","full_name":"dappros/ethora-mcp-server","owner":"dappros","description":"Model Context Protocol server for Ethora: login, app \u0026 chat management, and wallet tools (ERC-20) for MCP clients (Cursor, VS Code, Claude).","archived":false,"fork":false,"pushed_at":"2026-05-26T14:21:57.000Z","size":353,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T16:26:09.490Z","etag":null,"topics":["ai-agents","chat-api","claude","claude-desktop","cline","cursor","erc20","ethora","function-calling","mcp","mcp-server","model-context-protocol","nodejs","npm-package","tool-calling","typescript","vscode","wallet","web3","windsurf"],"latest_commit_sha":null,"homepage":"https://ethora.com/ai-sdk/mcp-server/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dappros.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-06T13:54:32.000Z","updated_at":"2026-05-14T14:23:05.000Z","dependencies_parsed_at":"2025-08-06T15:52:53.861Z","dependency_job_id":"17c15bf0-2421-4cd8-8713-71b3f206e48b","html_url":"https://github.com/dappros/ethora-mcp-server","commit_stats":null,"previous_names":["dappros/ethora-mcp-server","dappros/ethora-mcp-cli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/dappros/ethora-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dappros%2Fethora-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dappros%2Fethora-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dappros%2Fethora-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dappros%2Fethora-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dappros","download_url":"https://codeload.github.com/dappros/ethora-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dappros%2Fethora-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33590884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","chat-api","claude","claude-desktop","cline","cursor","erc20","ethora","function-calling","mcp","mcp-server","model-context-protocol","nodejs","npm-package","tool-calling","typescript","vscode","wallet","web3","windsurf"],"created_at":"2025-08-21T22:30:05.163Z","updated_at":"2026-05-28T01:30:36.823Z","avatar_url":"https://github.com/dappros.png","language":"TypeScript","funding_links":[],"categories":["💬 Communication"],"sub_categories":[],"readme":"# Ethora MCP Server (Model Context Protocol)\n\n[![npm](https://img.shields.io/npm/v/@ethora/mcp-server.svg)](https://www.npmjs.com/package/@ethora/mcp-server)\n[![Node](https://img.shields.io/badge/node-%E2%89%A518.x-blue.svg)](#)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=ethora\u0026config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBldGhvcmEvbWNwLXNlcnZlciJdfQ%3D%3D)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522ethora%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540ethora%252Fmcp-server%2522%255D%257D)\n[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522ethora%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540ethora%252Fmcp-server%2522%255D%257D)\n\n\u003e One-click install for Cursor and VS Code (buttons above). For Claude Code, Claude Desktop, GitHub Copilot, Gemini CLI, Codex CLI, Windsurf, and Cline, see [Using with MCP Clients](#-using-with-mcp-clients) below.\n\nAn MCP (Model Context Protocol) CLI/server that connects popular MCP clients to the **Ethora** platform — an open-source **chat \u0026 messaging platform with a built-in AI agent / chatbot framework**. This runs locally on a developer machine via stdio rather than as a hosted Ethora service.  \nUse it from **Cursor**, **VS Code MCP**, **Claude Desktop**, or **Windsurf/Cline** to manage apps and chat rooms, broadcast messages, deploy AI agents / chatbots with RAG sources, and automate B2B provisioning workflows. (ERC-20 wallet tools are also included — see the tool list below.)\n\n**Part of the [Ethora SDK ecosystem](https://github.com/dappros/ethora#ecosystem)** — see all SDKs, tools, and sample apps. Follow cross-SDK updates in the [Release Notes](https://github.com/dappros/ethora/blob/main/RELEASE-NOTES.md).\n\n- npm: \u003chttps://www.npmjs.com/package/@ethora/mcp-server\u003e\n- Default Ethora API: `https://api.chat.ethora.com/v1` (Swagger: \u003chttps://api.chat.ethora.com/api-docs/#/\u003e)\n\n---\n\n## ✨ What you get\n\n- Talk to the Ethora platform directly from your IDE or AI agent client (Cursor, VS Code MCP, Claude Desktop, Windsurf / Cline).\n- Both **user-auth** flows (login/register, files, owner/admin endpoints) and **B2B / app-token** flows (tenant provisioning, broadcast jobs, async user batches, AI bot config).\n- Built-in recipes, prompts, and generators for the most common Ethora workflows (Vite/Next chat-component setup, B2B bootstrap, AI-bot enablement, RAG sources).\n- Standard tool response envelope (`{ ok, ts, meta, data | error }`) so agent code can reason about success/failure consistently.\n\n## 🚦 Just trying it? (60-second quickstart)\n\nDon't read the auth modes yet. Once the server is connected in your client, ask your agent to run, in order:\n\n1. **`ethora-doctor`** — confirms the server is up and can reach the Ethora API. No credentials needed.\n2. **`ethora-configure`** with your `appJwt` → **`ethora-auth-use-user`** → **`ethora-user-login`** with an email + password.\n3. **`ethora-app-list`** — you're in; this lists your apps.\n\nThat's the local-developer path. Need server-side automation instead? Jump to [B2B mode](#2-b2b-mode). Lost at any point, call **`ethora-help`** — it reads your current state and tells you the next call.\n\n## 🔐 Two typical usage modes\n\n### 1) User Auth mode\n\nBest for:\n\n- developers trying Ethora locally\n- tenant admins / app owners using MCP manually\n- flows that start with `ethora-user-login`\n\nHow it works:\n\n- configure `ETHORA_APP_JWT` once for login/register bootstrap\n- switch to `ethora-auth-use-user`\n- call `ethora-user-login`\n- use user-auth tools such as files and legacy owner/admin endpoints\n\n### 2) B2B mode\n\nBest for:\n\n- permanent backend integrations\n- partner provisioning flows\n- autonomous agents operating Ethora without a human user session\n\nHow it works:\n\n- configure `ETHORA_B2B_TOKEN`\n- switch to `ethora-auth-use-b2b` for explicit tenant-actor `/v2/apps/:appId/...` routes\n- optionally switch into `ethora-auth-use-app` after `ethora-app-select` when you want app-scoped convenience routes powered by `appToken`\n\nRule of thumb:\n\n- first-time local use usually starts with **User Auth**\n- repeatable automation usually starts with **B2B**, then often moves into **app-token** mode for one selected app\n\n### Prompts \u0026 Resources (P2: dev-facing docs)\n\n- **Resources** (loadable docs into context)\n  - `ethora://docs/auth-map` — appJwt vs appToken vs b2bToken\n  - `ethora://docs/chat-component/quickstart` — Vite/Next quickstart + replacing demo tokens\n  - `ethora://docs/sdk-backend/quickstart` — backend integration quickstart\n  - `ethora://docs/recipes` — common tool sequences (broadcast/sources/files/bot)\n- **Prompts**\n  - `ethora-auth-map`\n  - `ethora-vite-quickstart`\n  - `ethora-nextjs-quickstart`\n  - `ethora-backend-sdk-quickstart`\n  - `ethora-recipes`\n\n### Generators (no shell, no file writes)\n\n- `ethora-generate-chat-component-app-tsx` — ready-to-paste `App.tsx` snippet for `@ethora/chat-component`\n- `ethora-generate-env-examples` — `.env.example` templates for:\n  - frontend chat component\n  - backend SDK integration\n  - MCP usage (`ETHORA_API_URL`, `ETHORA_APP_JWT`, `ETHORA_B2B_TOKEN`)\n- `ethora-generate-b2b-bootstrap-runbook` — minimal “call these MCP tools in order” runbook for B2B bootstrap\n\nTip: to list runnable recipes without calling `ethora-help`, call `ethora-run-recipe` with `goal: \"auto\"` and omit `recipeId`.\n\n- **Session / Config**\n  - `ethora-configure` — set API URL plus App JWT / B2B token / appToken for this MCP session\n  - `ethora-status` — show configured API URL, active auth mode, and which credentials are present\n  - `ethora-help` — task-oriented help (recommended next calls + “one-click recipes” based on current state)\n  - `ethora-run-recipe` — execute a built-in recipe by id (sequential steps; no shell, no file writes)\n  - `ethora-doctor` — validate config + ping the configured Ethora API for both user and B2B usage\n  - `ethora-app-select` — select current appId and optionally set appToken\n  - `ethora-auth-use-app` — switch to app-token auth mode for app-scoped operations\n  - `ethora-auth-use-user` — switch to user-session auth mode\n  - `ethora-auth-use-b2b` — switch to tenant-actor B2B `x-custom-token` auth mode\n\n- **Chats (v2)**\n  - `ethora-chats-broadcast-v2` — enqueue broadcast job using app-token auth or B2B + explicit `appId`\n  - `ethora-chats-broadcast-job-v2` — get broadcast job status/results using app-token auth or B2B + explicit `appId`\n  - `ethora-wait-broadcast-job-v2` — poll broadcast job until completed/failed using app-token auth or B2B + explicit `appId`\n  - `ethora-chats-message-v2` — send a test/automation message through the app chat surface (requires app-token auth)\n  - `ethora-chats-history-v2` — read persisted automation/test history for private or group sessions (requires app-token auth)\n\n- **Users (v2 async batch)**\n  - `ethora-users-batch-create-v2` — create async users batch job (requires B2B auth)\n  - `ethora-users-batch-job-v2` — get users batch job status/results (requires B2B auth)\n  - `ethora-wait-users-batch-job-v2` — poll users batch job until completed/failed (requires B2B auth)\n\n- **Files (v2)**\n- **Bot / Agent (v2)**\n  - `ethora-bot-get-v2` — get bot status/settings using app-token auth or B2B + explicit `appId`\n  - `ethora-bot-update-v2` — update bot settings using app-token auth or B2B + explicit `appId`\n  - `ethora-bot-enable-v2` — enable bot using app-token auth or B2B + explicit `appId`\n  - `ethora-bot-disable-v2` — disable bot using app-token auth or B2B + explicit `appId`\n  - `ethora-bot-widget-v2` — get widget/embed config and public widget URL metadata (app-token auth)\n  - `ethora-agents-list-v2` — list reusable saved agents for the current app owner (app-token auth)\n  - `ethora-agents-get-v2` — get one reusable saved agent (app-token auth)\n  - `ethora-agents-create-v2` — create a reusable saved agent (app-token auth)\n  - `ethora-agents-update-v2` — update a reusable saved agent (app-token auth)\n  - `ethora-agents-clone-v2` — clone a reusable saved agent (app-token auth)\n  - `ethora-agents-activate-v2` — bind a saved agent as the active bot for the selected app (app-token auth)\n  - `ethora-bot-message-v2` — compatibility alias for `ethora-chats-message-v2`\n  - `ethora-bot-history-v2` — compatibility alias for `ethora-chats-history-v2`\n\n  - `ethora-files-upload-v2` — upload files (requires user auth)\n  - `ethora-files-get-v2` — list/get files (requires user auth)\n  - `ethora-files-delete-v2` — delete file by id (requires user auth)\n\n- **Sources**\n  - `ethora-sources-site-crawl` — crawl a URL (requires user auth)\n  - `ethora-sources-site-reindex` — reindex URL by urlId (requires user auth)\n  - `ethora-sources-site-delete-url` — delete by URL (requires user auth)\n  - `ethora-sources-site-delete-url-v2` — batch delete URLs (requires user auth)\n  - `ethora-sources-docs-upload` — upload docs for ingestion (requires user auth)\n  - `ethora-sources-docs-delete` — delete ingested doc by id (requires user auth)\n  - `ethora-sources-site-crawl-v2` — crawl a URL using app-token auth or B2B + explicit `appId`\n  - `ethora-sources-site-reindex-v2` — reindex URL by urlId using app-token auth or B2B + explicit `appId`\n  - `ethora-sources-site-crawl-v2-wait` — single-call long-timeout helper for crawl (app-token auth)\n  - `ethora-sources-site-reindex-v2-wait` — single-call long-timeout helper for reindex (app-token auth)\n  - `ethora-sources-site-list-v2` — list crawled site sources and current tags using app-token auth or B2B + explicit `appId`\n  - `ethora-sources-site-tags-update-v2` — set/update tags for a crawled site source using app-token auth or B2B + explicit `appId`\n  - `ethora-sources-site-delete-url-v2` — delete one crawled URL by URL using app-token auth or B2B + explicit `appId`\n  - `ethora-sources-site-delete-url-v2-batch` — batch delete crawled source records by id using app-token auth or B2B + explicit `appId`\n  - `ethora-sources-docs-upload-v2` — upload docs for ingestion using app-token auth or B2B + explicit `appId`\n  - `ethora-sources-docs-list-v2` — list indexed documents and current tags using app-token auth or B2B + explicit `appId`\n  - `ethora-sources-docs-tags-update-v2` — set/update tags for an indexed document using app-token auth or B2B + explicit `appId`\n  - `ethora-sources-docs-delete-v2` — delete doc by id using app-token auth or B2B + explicit `appId`\n\n- **Auth \u0026 Accounts**\n  - `ethora-user-login` — login user (email + password)\n  - `ethora-user-register` — register user (email + first/last name)\n\n- **Applications**\n  - `ethora-app-create` — create app\n  - `ethora-app-update` — update app\n  - `ethora-app-delete` — delete app\n  - `ethora-app-list` — list apps\n  - `ethora-b2b-app-create` — create app using B2B auth (x-custom-token)\n  - `ethora-b2b-app-bootstrap-ai` — create app → index sources → configure/enable bot, including runtime LLM selection (B2B automation)\n  - `ethora-app-tokens-list-v2` — list app token metadata (B2B auth)\n  - `ethora-app-tokens-create-v2` — create new app token (returned once) (B2B auth)\n  - `ethora-app-tokens-rotate-v2` — rotate token (revoke old, return new once) (B2B auth)\n  - `ethora-app-tokens-revoke-v2` — revoke token by tokenId (idempotent) (B2B auth)\n  - `ethora-b2b-app-provision` — create app + create tokens + provision rooms + configure bot, including runtime LLM selection (B2B orchestrator)\n\n- **Chat \u0026 Rooms**\n  - `ethora-app-get-default-rooms` — list default rooms\n  - `ethora-app-get-default-rooms-with-app-id` — rooms for a given app\n  - `ethora-app-create-chat` — create chat for app\n  - `ethora-app-delete-chat` — delete chat\n\n- **Wallet**\n  - `ethora-wallet-get-balance` — get balance\n  - `ethora-wallet-erc20-transfer` — send ERC-20 tokens\n\n\u003e Tool names above reflect the functional areas exposed by the server. Your exact tool names may vary slightly by version; run the client’s “list tools” to confirm.\n\n\n\u003cimg width=\"1670\" height=\"995\" alt=\"settings\" src=\"https://github.com/user-attachments/assets/5a3e98da-5362-4ed2-9080-473510ad2837\" /\u003e\n\u003cimg width=\"1691\" height=\"1011\" alt=\"login\" src=\"https://github.com/user-attachments/assets/c70fc2d7-4686-4619-aaad-0ca966ac2912\" /\u003e\n\n\n## 📦 Install / Run\n\n### Pre-requisites\nBefore you begin, ensure you have the following:\n- Node.js installed on your system (recommended version 18.x or higher).\n\n### Install\n\nThe server is distributed as an npm package and is typically launched by MCP clients via **npx**:\n\n```bash\nnpx -y @ethora/mcp-server\n```\n\nNo global install is required.\n\n---\n\n## 🔐 Configuration (env vars)\n\nThis MCP server supports both the local user-auth flow and the server-side B2B flow.\n\nCore values:\n\n- **Ethora API URL** (where to send requests)\n- **Ethora App JWT** (used only for login/register bootstrap in user-auth mode)\n- **Ethora B2B Token** (used for tenant-actor server-to-server flows)\n\nYou can provide these either:\n- via **env vars**, or\n- at runtime via the **`ethora-configure`** tool (in-memory; resets when MCP process restarts)\n\n### Supported env vars\n\n- `ETHORA_API_URL`: full API URL (example: `https://api.chat.ethora.com/v1`, `http://localhost:8080/v1`)\n- `ETHORA_BASE_URL`: base host URL (example: `https://api.chat.ethora.com`, `http://localhost:8080`)  \n  If provided, the server will default to `.../v1`.\n- `ETHORA_APP_JWT`: App JWT string, usually starting with `JWT ...`\n- `ETHORA_B2B_TOKEN`: B2B server token for `x-custom-token` auth (JWT with `type=server`)\n- `ETHORA_MCP_ENABLE_DANGEROUS_TOOLS`: enable destructive tools (default: disabled). Set to `true` to expose:\n  - app deletion tools\n  - wallet transfer tools\n  - bulk delete tools\n\n\u003e Security: **never** commit App JWTs, B2B tokens, or appTokens to git. Configure them via env vars, the MCP client secret store, or your own backend.\n\n---\n\n## 🧱 Standard response envelope (tools)\n\nAll tools return JSON in a consistent envelope:\n\n- Success: `{ ok: true, ts, meta, data }`\n- Error: `{ ok: false, ts, meta, error }`, where `error` includes:\n  - `code`: stable string (prefer API `code`, otherwise inferred)\n  - `httpStatus`: HTTP status when the failure came from an API call\n  - `requestId`: request/correlation id if returned by API\n  - `hint`: 1-line “what to do next”\n\n---\n\n## 🚀 Using with MCP Clients\n\nEvery client runs the same thing — `npx -y @ethora/mcp-server` over stdio. One-click buttons exist for **Cursor** and **VS Code** (top of this README). For the rest it's a short config block or a one-line command.\n\n### Cursor\n\nUse the **[Add to Cursor](https://cursor.com/en/install-mcp?name=ethora\u0026config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBldGhvcmEvbWNwLXNlcnZlciJdfQ%3D%3D)** button above, or manually: **Settings → MCP → Add new global MCP server**:\n\n```json\n{\n  \"mcpServers\": {\n    \"ethora\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ethora/mcp-server\"]\n    }\n  }\n}\n```\n\n### VS Code (and GitHub Copilot)\n\nUse the **Install in VS Code** button above, or add a `.vscode/mcp.json` file (project-level) — note the key is `servers`:\n\n```json\n{\n  \"servers\": {\n    \"ethora\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ethora/mcp-server\"]\n    }\n  }\n}\n```\n\nGitHub Copilot's **agent mode** in VS Code reads this same `.vscode/mcp.json` — no separate setup. (For a user-level install instead, put the `servers` block under `\"mcp\"` in your User Settings JSON.)\n\n### Claude Code\n\nOne command:\n\n```bash\nclaude mcp add ethora -- npx -y @ethora/mcp-server\n```\n\nAdd `--scope user` to make it available in every project. Verify with `claude mcp list`.\n\nTo pre-configure credentials, pass them as env vars with `-e` (recommended over the `ethora-configure` tool — see note below):\n\n```bash\nclaude mcp add ethora \\\n  -e ETHORA_API_URL=https://api.chat.ethora.com/v1 \\\n  -e ETHORA_B2B_TOKEN=\u003cyour-b2b-token\u003e \\\n  -- npx -y @ethora/mcp-server\n```\n\n\u003e **Secrets note:** prefer env vars (above) or your MCP client's secret store for credentials. The `ethora-configure` tool also works, but it passes secrets as tool arguments, which means they end up in the conversation transcript. Use it for quick local testing, not for tokens you care about.\n\n### Claude Desktop\n\n**Settings → Developer → Edit Config**, open `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ethora\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ethora/mcp-server\"]\n    }\n  }\n}\n```\n\n### Gemini CLI\n\nAdd to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (per project):\n\n```json\n{\n  \"mcpServers\": {\n    \"ethora\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ethora/mcp-server\"]\n    }\n  }\n}\n```\n\n### Codex CLI\n\nAdd to `~/.codex/config.toml` — note the table name is `mcp_servers` (underscore; `mcp-servers` is silently ignored):\n\n```toml\n[mcp_servers.ethora]\ncommand = \"npx\"\nargs = [\"-y\", \"@ethora/mcp-server\"]\n```\n\n### Windsurf\n\n**Settings → Cascade → MCP Servers → View raw config** (`~/.codeium/windsurf/mcp_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"ethora\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ethora/mcp-server\"]\n    }\n  }\n}\n```\n\n### Cline\n\nOpen the MCP servers panel and edit `cline_mcp_settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ethora\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ethora/mcp-server\"]\n    }\n  }\n}\n```\n\n---\n\n## 🧪 Quick test\n\nAfter the server shows as **connected** in your client:\n\n- Run `list tools` (client command) to verify Ethora tools are available.\n- Check config/connectivity: call `ethora-doctor` (or `ethora-status`)\n- For a first local/manual test:\n  - call `ethora-configure` with `apiUrl` / `appJwt`\n  - call `ethora-auth-use-user`\n  - call `ethora-user-login`\n  - then try `ethora-app-list` or `ethora-wallet-get-balance`\n- For a server-side/B2B test:\n  - call `ethora-configure` with `apiUrl` / `b2bToken`\n  - call `ethora-auth-use-b2b`\n  - then try `ethora-b2b-app-create` or `ethora-app-tokens-list-v2`\n\n---\n\n## 🧭 P1: B2B “create app → index sources → deploy bot” in one call\n\nPre-reqs:\n- Configure `ETHORA_API_URL` (or call `ethora-configure`)\n- Configure `ETHORA_B2B_TOKEN` (or call `ethora-configure` with `b2bToken`)\n- Ensure your Ethora backend is configured with AI service URL/secret (for bot activation)\n\nSuggested flow:\n- Call `ethora-auth-use-b2b`\n- Call `ethora-b2b-app-bootstrap-ai` with:\n  - `displayName`\n  - optional `savedAgentId`\n  - optional `crawlUrl`\n  - optional `docs[]` (base64)\n  - `enableBot: true`\n  - optional `llmProvider`\n  - optional `llmModel`\n\nIt will:\n- create the app (B2B)\n- set current app context (best-effort)\n- index sources via `/v2/sources/*` (app-token auth)\n- configure and/or enable bot (best-effort)\n\n### Example payloads\n\nMinimal (create app only):\n\n```json\n{\n  \"displayName\": \"Acme AI Demo\",\n  \"setAsCurrent\": true\n}\n```\n\nCreate app + crawl a website + enable bot:\n\n```json\n{\n  \"displayName\": \"Acme AI Demo\",\n  \"savedAgentId\": \"6790abc1234567890def1111\",\n  \"crawlUrl\": \"https://example.com\",\n  \"followLink\": true,\n  \"enableBot\": true,\n  \"botTrigger\": \"/bot\",\n  \"llmProvider\": \"openai\",\n  \"llmModel\": \"gpt-4o-mini\"\n}\n```\n\nCreate app + upload docs + enable bot:\n\n```json\n{\n  \"displayName\": \"Acme AI Demo\",\n  \"docs\": [\n    {\n      \"name\": \"faq.pdf\",\n      \"mimeType\": \"application/pdf\",\n      \"base64\": \"BASE64_PDF_CONTENT_HERE\"\n    }\n  ],\n  \"enableBot\": true,\n  \"llmProvider\": \"openai\",\n  \"llmModel\": \"gpt-4o-mini\"\n}\n```\n\nProvision app + token + default rooms + bot settings:\n\n```json\n{\n  \"displayName\": \"Acme Support\",\n  \"savedAgentId\": \"6790abc1234567890def1111\",\n  \"tokenLabels\": [\"default\", \"staging\"],\n  \"rooms\": [\n    { \"title\": \"General\" },\n    { \"title\": \"Support\", \"pinned\": true }\n  ],\n  \"enableBot\": true,\n  \"botTrigger\": \"/bot\",\n  \"botPrompt\": \"You are the Acme support assistant.\",\n  \"botGreetingMessage\": \"Hello. How can I help?\",\n  \"llmProvider\": \"openai\",\n  \"llmModel\": \"gpt-4o-mini\"\n}\n```\n\nProvider/model note:\n- Common values are `openai` and `openai-compatible`.\n- The effective provider/model must also be enabled by your Ethora backend + AI service environment.\n\n---\n\n## 🤖 App automation loop\n\nOnce you already have an app selected with `appToken` auth:\n\n- call `ethora-auth-use-app`\n- call `ethora-bot-get-v2` to inspect current bot status and prompt settings\n- call `ethora-sources-site-list-v2` and `ethora-sources-docs-list-v2` to inspect indexed sources\n- call `ethora-sources-site-tags-update-v2` or `ethora-sources-docs-tags-update-v2` to organize retrieval by tags\n- call `ethora-chats-message-v2` / `ethora-chats-history-v2` if your backend exposes the chat automation surface on the same API host\n\nExample: apply retrieval tags to a crawled source\n\n```json\n{\n  \"sourceId\": \"6790abc1234567890def1234\",\n  \"tags\": [\"support\", \"faq\", \"billing\"]\n}\n```\n\nExample: apply retrieval tags to an indexed document\n\n```json\n{\n  \"docId\": \"6790abc1234567890def1235\",\n  \"tags\": [\"support\", \"faq\"]\n}\n```\n\n---\n\n## 🛡️ Security notes\n\n- **Never** hardcode API keys in shared config. Prefer client-side secret stores.\n- Use **least privilege** keys and consider **allowlists/rate limits** on your Ethora backend.\n- Rotate credentials regularly in production use.\n\n### CI security scans (report-only)\n\nThis repo runs **report-only** scans on pushes/PRs:\n- **gitleaks** for secret scanning\n- **semgrep** for basic SAST\n\n---\n\n## 🧰 Development\n\nClone and run locally:\n\n```bash\ngit clone https://github.com/dappros/ethora-mcp-server.git\ncd ethora-mcp-server\nnpm install\nnpm run build\nnpm start\n```\n\nSuggested scripts (if not present):\n```json\n{\n  \"scripts\": {\n    \"build\": \"tsc -p .\",\n    \"start\": \"node dist/index.js\",\n    \"dev\": \"tsx src/index.ts\"\n  }\n}\n```\n\n---\n\n## ❓ Troubleshooting\n\n- **Client can’t connect**: Ensure `npx @ethora/mcp-server` runs locally without errors. Check Node ≥ 18.\n- **Auth errors**: Verify `ETHORA_BASE_URL` and any required secrets are set in the client’s environment.\n- **Tools missing**: Restart the MCP client and inspect server logs for registration errors.\n- **Network**: Confirm outbound access from the IDE to your Ethora host.\n\n---\n\n## 🔗 Related Repos\n\n- **Ethora Chat Component** — our React chat component used in widgets and stand-alone apps\n  https://github.com/dappros/ethora-chat-component\n- **Ethora WP Plugin** — WordPress integration  \n  https://github.com/dappros/ethora-wp-plugin\n- **RAG Demos** — RAG AI assistant examples  \n  https://github.com/dappros/rag_demos\n\n---\n\n## 📜 License\n\nSee [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdappros%2Fethora-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdappros%2Fethora-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdappros%2Fethora-mcp-server/lists"}