io.github.dappros/ethora-mcp-server

Official91 toolsLive

by dappros · TypeScript

Ethora chat platform MCP: apps, users, rooms, AI agents, chat widgets. Hosted or stdio.

io.github.dappros/ethora-mcp-server (Model Context Protocol)

This MCP server integrates the Ethora chat & messaging platform with the Model Context Protocol, supporting chat ops, AI agents, RAG, and automation. It is distributed as the npm package @ethora/mcp-server and is associated with topics including model-context-protocol, mcp-server, and tool-calling.

🛠️ Key Features

Chat ops for Ethora
AI agents
RAG
Automation
Tool-calling / function-calling support

🚀 Use Cases

Chat-driven AI agent workflows in Ethora
Retrieval-augmented generation tasks
Automated operations triggered via chat and agents
Ethereum-related integrations tied to wallet and ERC20 topics

⚡ Developer Benefits

MCP server for Model Context Protocol tooling
Node.js/TypeScript npm package
Compatible with editor workflows referenced by Cursor and VS Code installation

⚠️ Limitations

Source data does not include explicit constraints, supported runtimes beyond Node.js (≥18.x), or the exact tool list.

Topics

ai-agentschat-apiclaudecursorethorafunction-callingmcpmcp-servermodel-context-protocolnodejsnpm-packagetool-callingtypescriptwindsurfchatgptmessagingremote-mcpai-assistantschat-widgetchatbot

Captured live from the server via tools/list.

ethora-configure

Set the Ethora API URL and credentials for this MCP session. Stores values in memory only; each call merges with omitted fields kept. Alternative to env vars (ETHORA_API_URL / ETHORA_APP_JWT / ETHORA_APP_TOKEN / ETHORA_B2B_TOKEN). On a hosted server `apiUrl` is fixed and cannot be changed; credentials are per session. Auth: none required — this establishes auth material. Errors: only if a value is structurally invalid. Follow with an `ethora-auth-use-*` tool to pick the active mode.

Parameters4

apiUrl	string	optional	Full Ethora API URL including the version path, e.g. `https://api.chat.ethora.com/v1` or `http://localhost:8080/v1`. If you only have the host, set ETHORA_BASE_URL env instead and the server appends `/v1`.
appJwt	string	optional	Ethora App JWT, used only to bootstrap login/register in user-auth mode. Usually starts with `JWT `. Secret — never commit it.
appToken	string	optional	Per-app appToken for app-scoped flows (broadcast, sources, bot). Setting this makes app-token auth available via `ethora-auth-use-app`. Secret.
b2bToken	string	optional	B2B server token for tenant-actor `x-custom-token` auth (a JWT with `type=server`). Required for B2B provisioning flows. Secret.

Raw schema

{
  "type": "object",
  "properties": {
    "apiUrl": {
      "type": "string",
      "description": "Full Ethora API URL including the version path, e.g. `https://api.chat.ethora.com/v1` or `http://localhost:8080/v1`. If you only have the host, set ETHORA_BASE_URL env instead and the server appends `/v1`."
    },
    "appJwt": {
      "type": "string",
      "description": "Ethora App JWT, used only to bootstrap login/register in user-auth mode. Usually starts with `JWT `. Secret — never commit it."
    },
    "appToken": {
      "type": "string",
      "description": "Per-app appToken for app-scoped flows (broadcast, sources, bot). Setting this makes app-token auth available via `ethora-auth-use-app`. Secret."
    },
    "b2bToken": {
      "type": "string",
      "description": "B2B server token for tenant-actor `x-custom-token` auth (a JWT with `type=server`). Required for B2B provisioning flows. Secret."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-status

Report the current Ethora MCP session state: configured API URL, active auth mode, which credentials are present (booleans like `hasAppJwt` — values never echoed), the selected appId/agentId, and `hosted`/`sessionId` on the hosted (Streamable HTTP) server. Auth: none required. Errors: effectively none. Related: `ethora-doctor` for an active connectivity check.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

ethora-help

Task-oriented orientation for this MCP server: explains the three Ethora auth modes (user / app-token / B2B) and recommends next tool calls + recipes based on current session state. Auth: none required — inspects state, no API calls. Errors: effectively none. Related: pass a recommended recipe id to `ethora-run-recipe`.

Parameters1

goal

string

optional

Goal hint to tailor the recommendations and recipe list. Omit or use `auto` to get recommendations inferred from the current session state.

Raw schema

{
  "type": "object",
  "properties": {
    "goal": {
      "type": "string",
      "enum": [
        "auto",
        "b2b-bootstrap-ai",
        "broadcast",
        "sources-ingest",
        "files-upload",
        "bot-manage",
        "chat-test",
        "widget",
        "user-login"
      ],
      "description": "Goal hint to tailor the recommendations and recipe list. Omit or use `auto` to get recommendations inferred from the current session state."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-run-recipe

Execute a built-in recipe — an ordered sequence of this server's own tool calls — by id. Recipes capture common flows (B2B bootstrap, broadcast, sources ingest). Use `dryRun: true` to preview resolved steps. Omit `recipeId` to list runnable recipes for a `goal`. Requires: the inputs the chosen recipe lists; call without `recipeId` first to see the recipes and their required inputs. Auth: depends on the recipe's steps — configure those first (see `ethora-help`). Errors: stops at the first failing step and returns the partial log; a missing required `vars` entry fails fast before any step runs.

Parameters4

recipeId	string	optional	Id of the recipe to run. Omit to instead list the runnable recipes for the selected `goal` (get ids from `ethora-help`).
goal	string	optional	Goal scope used to look up recipes when `recipeId` is omitted. Defaults to `auto`.
vars	object	optional	Key/value substitutions injected into recipe steps (e.g. appId, appToken, b2bToken, appJwt, email, password, apiUrl). A recipe declares which vars it requires; missing required vars fail the run before any step executes.
dryRun	boolean	optional	If true, resolve and return the step list with `vars` substituted but execute nothing. Use this to preview a recipe before running it for real.

Raw schema

{
  "type": "object",
  "properties": {
    "recipeId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the recipe to run. Omit to instead list the runnable recipes for the selected `goal` (get ids from `ethora-help`)."
    },
    "goal": {
      "type": "string",
      "enum": [
        "auto",
        "b2b-bootstrap-ai",
        "broadcast",
        "sources-ingest",
        "files-upload",
        "bot-manage",
        "chat-test",
        "widget",
        "user-login"
      ],
      "description": "Goal scope used to look up recipes when `recipeId` is omitted. Defaults to `auto`."
    },
    "vars": {
      "type": "object",
      "additionalProperties": {},
      "description": "Key/value substitutions injected into recipe steps (e.g. appId, appToken, b2bToken, appJwt, email, password, apiUrl). A recipe declares which vars it requires; missing required vars fail the run before any step executes."
    },
    "dryRun": {
      "type": "boolean",
      "description": "If true, resolve and return the step list with `vars` substituted but execute nothing. Use this to preview a recipe before running it for real."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-doctor

Diagnose the session: validate the config is internally consistent for the active auth mode and ping the Ethora API (`GET /v1/ping`). Returns `{ state, checks, ping, suggestions }`. Auth: none required; report is tailored to whatever credentials are set. Errors: rarely throws — instead returns `suggestions` and a `ping.ok: false` block when the API is unreachable.

Parameters1

timeoutMs

integer

optional

HTTP timeout in milliseconds for the ping request. Defaults to 3000. Raise it on slow links, lower it to fail fast.

Raw schema

{
  "type": "object",
  "properties": {
    "timeoutMs": {
      "type": "integer",
      "minimum": 500,
      "maximum": 20000,
      "description": "HTTP timeout in milliseconds for the ping request. Defaults to 3000. Raise it on slow links, lower it to fail fast."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-auth-use-app

Switch this session's active auth mode to app-token, so subsequent app-scoped calls authenticate with the configured `appToken`. Auth: requires an `appToken` to already be configured (via `ethora-configure`, ETHORA_APP_TOKEN env, or `ethora-app-select`). Errors: returns an error if no `appToken` is configured. Related: use after `ethora-app-select`.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

ethora-auth-use-user

Switch this session's active auth mode to user-session, so subsequent calls authenticate as a logged-in Ethora user. Auth: the switch needs nothing, but user-auth tools only work once `ethora-user-login` stores a user token (login also needs a configured `appJwt`). Errors: none on the switch; downstream tools return 401 until login succeeds. Related: follow with `ethora-user-login`.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

ethora-auth-use-b2b

Switch this session's active auth mode to B2B, so subsequent calls authenticate as a tenant actor via the `x-custom-token` header. Auth: requires a `b2bToken` (JWT with `type=server`) to already be configured (via `ethora-configure` or ETHORA_B2B_TOKEN env). Errors: returns an error if no `b2bToken` is configured. Related: server-side automation — pairs with `ethora-b2b-app-create`, `ethora-users-batch-create-v2`, `ethora-app-tokens-*-v2`.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

ethora-app-select

Set the current app context for this session so app-scoped tools can omit their `appId` argument. Stores `currentAppId` and, if given, `appToken` (which defaults the auth mode to app-token unless `authMode` overrides). Auth: none required to set the context. Errors: effectively none — a non-existent `appId` is not validated here; the first app-scoped API call surfaces the 404. Related: pairs with `ethora-auth-use-app`.

Parameters3

appId	string	required	24-char hex Ethora appId to set as the current context. Get it from `ethora-app-list`, `ethora-app-create`, or a B2B create/provision response.
appToken	string	optional	Per-app appToken to store alongside the appId. If provided, the active auth mode switches to app-token (unless `authMode` says otherwise). Secret.
authMode	string	optional	Auth mode to keep after selecting the app. Omit to let the mode default to app-token when an `appToken` is given, or stay unchanged otherwise.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex Ethora appId to set as the current context. Get it from `ethora-app-list`, `ethora-app-create`, or a B2B create/provision response."
    },
    "appToken": {
      "type": "string",
      "description": "Per-app appToken to store alongside the appId. If provided, the active auth mode switches to app-token (unless `authMode` says otherwise). Secret."
    },
    "authMode": {
      "type": "string",
      "enum": [
        "app",
        "user",
        "b2b"
      ],
      "description": "Auth mode to keep after selecting the app. Omit to let the mode default to app-token when an `appToken` is given, or stay unchanged otherwise."
    }
  },
  "required": [
    "appId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-chats-broadcast-v2

Enqueue an asynchronous broadcast job posting a message to one or more chat rooms of an app — returns a `jobId`; messages are not sent synchronously. Targeting is exclusive: `allRooms`, `chatIds`, or `chatNames`, not a mix. Requires: a selected app with at least one room (`ethora-app-create-chat`). Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 400 no target or conflicting targets; 404 unknown `appId` or room. Related: track with `ethora-wait-broadcast-job-v2`.

Parameters5

appId	string	optional	24-char hex appId to broadcast in. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode (the token determines the app).
text	string	required	Plain-text message body to broadcast to the targeted rooms.
allRooms	boolean	optional	If true, broadcast to every room in the app. Mutually exclusive with `chatIds` and `chatNames`.
chatIds	array	optional	Explicit list of chat ids to target. Mutually exclusive with `allRooms` and `chatNames`.
chatNames	array	optional	Explicit list of chat JIDs or localparts to target. Mutually exclusive with `allRooms` and `chatIds`.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId to broadcast in. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode (the token determines the app)."
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "description": "Plain-text message body to broadcast to the targeted rooms."
    },
    "allRooms": {
      "type": "boolean",
      "description": "If true, broadcast to every room in the app. Mutually exclusive with `chatIds` and `chatNames`."
    },
    "chatIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Explicit list of chat ids to target. Mutually exclusive with `allRooms` and `chatNames`."
    },
    "chatNames": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Explicit list of chat JIDs or localparts to target. Mutually exclusive with `allRooms` and `chatIds`."
    }
  },
  "required": [
    "text"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-chats-broadcast-job-v2

Fetch the current status and per-room results of a broadcast job by `jobId` (one-shot, no polling). Returns the job object with its `state` (pending/running/completed/failed). Requires: a selected app with at least one room (`ethora-app-create-chat`). Auth: app-token mode OR B2B mode with an explicit `appId` — must match the auth used to enqueue the job. Errors: 401/403 wrong auth; 404 unknown `jobId`. Related: `ethora-wait-broadcast-job-v2` for a blocking wait.

Parameters2

appId	string	optional	24-char hex appId the job belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
jobId	string	required	Job id returned by `ethora-chats-broadcast-v2`.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the job belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "jobId": {
      "type": "string",
      "description": "Job id returned by `ethora-chats-broadcast-v2`."
    }
  },
  "required": [
    "jobId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-wait-broadcast-job-v2

Block until a broadcast job reaches a terminal state (`completed` or `failed`) or until `timeoutMs` — read-only polling wrapper around `ethora-chats-broadcast-job-v2`. Returns `{ done, state, job }`, or `{ done: false, reason: "timeout" }` on timeout. Requires: a `jobId` returned by `ethora-chats-broadcast-job-v2`. Auth: app-token mode OR B2B mode with an explicit `appId` — must match the auth used to enqueue the job. Errors: 401/403 wrong auth; 404 unknown `jobId`.

Parameters4

appId	string	optional	24-char hex appId the job belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
jobId	string	required	Job id returned by `ethora-chats-broadcast-v2`.
timeoutMs	integer	optional	Maximum time to wait, in milliseconds. Default 60000. Caps at 300000 (5 min).
intervalMs	integer	optional	Delay between status checks, in milliseconds. Default 1000. Lower = more responsive but more API calls.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the job belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "jobId": {
      "type": "string",
      "minLength": 1,
      "description": "Job id returned by `ethora-chats-broadcast-v2`."
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 1000,
      "maximum": 300000,
      "description": "Maximum time to wait, in milliseconds. Default 60000. Caps at 300000 (5 min)."
    },
    "intervalMs": {
      "type": "integer",
      "minimum": 250,
      "maximum": 10000,
      "description": "Delay between status checks, in milliseconds. Default 1000. Lower = more responsive but more API calls."
    }
  },
  "required": [
    "jobId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-files-upload-v2

Upload 1–5 files to the authenticated user's Ethora file storage (`POST /v2/files`). Each upload is a new record (no overwrite-by-name); files passed as base64, 50MB max each. Auth: user-auth mode with an active user session (`ethora-user-login` first). Errors: 401 not logged in; 413 size limit exceeded; 422 unsupported mime type. Related: manage with `ethora-files-get-v2` / `ethora-files-delete-v2`.

Parameters1

files

array

required

1 to 5 files to upload in this call.

Raw schema

{
  "type": "object",
  "properties": {
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "File name including extension, e.g. `report.pdf`."
          },
          "mimeType": {
            "type": "string",
            "minLength": 1,
            "description": "MIME type of the content, e.g. `application/pdf`, `image/png`, `text/plain`."
          },
          "base64": {
            "type": "string",
            "minLength": 1,
            "description": "File content, base64-encoded. A `data:...;base64,` prefix is accepted and stripped. Max 50MB decoded per file."
          }
        },
        "required": [
          "name",
          "mimeType",
          "base64"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "1 to 5 files to upload in this call."
    }
  },
  "required": [
    "files"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-files-get-v2

List the authenticated user's files, or fetch one file's metadata by id (`GET /v2/files`). Returns an array when `id` is omitted, a single record when given. Requires: a file id from `ethora-files-upload-v2`. Auth: user-auth mode with an active user session. Errors: 401 not logged in; 404 unknown `id` or not owned by the user.

Parameters1

string

optional

File id to fetch a single record. Omit to list all files owned by the logged-in user.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "File id to fetch a single record. Omit to list all files owned by the logged-in user."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-files-delete-v2

Permanently delete one of the authenticated user's files by id (`DELETE /v2/files/:id`). Removes the record and its stored content; not reversible. Requires: a file id from `ethora-files-upload-v2`. Auth: user-auth mode with an active user session. Errors: 401 not logged in; 403 not owned by the user; 404 unknown `id`. Related: get ids from `ethora-files-get-v2`.

Parameters1

string

required

Id of the file to delete. Get it from `ethora-files-get-v2`.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the file to delete. Get it from `ethora-files-get-v2`."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-docs-upload

Upload documents (1–5; PDF, text, etc.) into an app's RAG sources (legacy user-auth route). Async — content becomes queryable once indexing finishes; files passed as base64, 50MB max each. Requires: a selected app (`ethora-app-select`) or an explicit `appId`. Auth: user-auth mode, active session; the user must own the app. Errors: 401 not logged in; 403 not owner; 413 too large; 422 unsupported document type. Related: app-token/B2B flows use `ethora-sources-docs-upload-v2`.

Parameters2

appId	string	optional	24-char hex appId to ingest into. Optional — defaults to the app set via `ethora-app-select`.
files	array	required	1 to 5 documents to ingest in this call.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId to ingest into. Optional — defaults to the app set via `ethora-app-select`."
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Document file name including extension, e.g. `handbook.pdf`."
          },
          "mimeType": {
            "type": "string",
            "minLength": 1,
            "description": "MIME type, e.g. `application/pdf`, `text/plain`, `text/markdown`."
          },
          "base64": {
            "type": "string",
            "minLength": 1,
            "description": "Document content, base64-encoded. A `data:...;base64,` prefix is accepted. Max 50MB decoded per file."
          }
        },
        "required": [
          "name",
          "mimeType",
          "base64"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "1 to 5 documents to ingest in this call."
    }
  },
  "required": [
    "files"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-docs-delete

Remove a previously ingested document from an app's RAG sources by `docId` (legacy user-auth route). Deletes the document record and its embeddings; not reversible. Requires: a document id from `ethora-sources-docs-list-v2`. Auth: user-auth mode, active session; the user must own the app. Errors: 401 not logged in; 403 not owner; 404 unknown `docId`. Related: get `docId` from `ethora-sources-docs-list-v2`; app-token/B2B uses `ethora-sources-docs-delete-v2`.

Parameters2

appId	string	optional	24-char hex appId the document belongs to. Optional — defaults to the app set via `ethora-app-select`.
docId	string	required	Id of the ingested document to delete. Get it from `ethora-sources-docs-list-v2`.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the document belongs to. Optional — defaults to the app set via `ethora-app-select`."
    },
    "docId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the ingested document to delete. Get it from `ethora-sources-docs-list-v2`."
    }
  },
  "required": [
    "docId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-site-crawl-v2

Crawl a website URL and ingest its content into an app's RAG sources (app-token / B2B variant of `ethora-sources-site-crawl`). Async — returns once the job is accepted; `followLink: true` follows in-domain links and can ingest many pages. Requires: a selected app (`ethora-app-select`) or an explicit `appId`. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 400 malformed `url`; 404 unknown `appId`. Related: `ethora-sources-site-crawl-v2-wait` (block until done).

Parameters3

appId	string	optional	24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
url	string	required	Absolute URL to crawl, e.g. `https://example.com/docs`.
followLink	boolean	optional	If true, also crawl in-domain links reachable from `url`. Can ingest many pages — use with care.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "url": {
      "type": "string",
      "minLength": 1,
      "description": "Absolute URL to crawl, e.g. `https://example.com/docs`."
    },
    "followLink": {
      "type": "boolean",
      "description": "If true, also crawl in-domain links reachable from `url`. Can ingest many pages — use with care."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-site-reindex-v2

Re-crawl and re-embed a previously crawled URL by its `urlId`, refreshing its RAG content (app-token / B2B variant of `ethora-sources-site-reindex`). Async — the existing source record is updated in place once indexing finishes. Requires: an indexed site URL from `ethora-sources-site-list-v2` (crawled with `ethora-sources-site-crawl-v2`). Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId` or `urlId`. Related: get `urlId` from `ethora-sources-site-list-v2`; `ethora-sources-site-reindex-v2-wait` blocks until done.

Parameters2

appId	string	optional	24-char hex appId the URL belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
urlId	string	required	Id of a previously crawled URL record. Get it from `ethora-sources-site-list-v2`.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the URL belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "urlId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of a previously crawled URL record. Get it from `ethora-sources-site-list-v2`."
    }
  },
  "required": [
    "urlId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-site-crawl-v2-wait

Crawl a website URL and wait for the crawl to finish: enqueues the job, then polls it until it reports `completed` or `failed`. Returns `{ done, status, jobId, polls, durationMs, result }`; `done: false` with a `note` means the budget ran out while the job was still running (it usually finishes server-side anyway). Requires: a selected app (`ethora-app-select`) or an explicit `appId`. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 400 malformed `url`; 504/timeout if it takes longer than `timeoutMs` (the job may still complete server-side — check with `ethora-sources-site-list-v2`).

Parameters4

appId	string	optional	24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
url	string	required	Absolute URL to crawl, e.g. `https://example.com/docs`.
followLink	boolean	optional	If true, also crawl in-domain links reachable from `url`. Can ingest many pages — use with care.
timeoutMs	integer	optional	How long to poll for the crawl to finish, in milliseconds. Default 45000, chosen to stay under the ~60s request timeout most MCP clients enforce. Caps at 600000 (10 min) for clients that allow longer calls.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "url": {
      "type": "string",
      "minLength": 1,
      "description": "Absolute URL to crawl, e.g. `https://example.com/docs`."
    },
    "followLink": {
      "type": "boolean",
      "description": "If true, also crawl in-domain links reachable from `url`. Can ingest many pages — use with care."
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 1000,
      "maximum": 600000,
      "description": "How long to poll for the crawl to finish, in milliseconds. Default 45000, chosen to stay under the ~60s request timeout most MCP clients enforce. Caps at 600000 (10 min) for clients that allow longer calls."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-site-reindex-v2-wait

Re-crawl and re-embed a previously crawled URL and wait for it to finish: enqueues the job, then polls it until it reports `completed` or `failed`. Returns `{ done, status, jobId, polls, durationMs, result }`; `done: false` with a `note` means the budget ran out while the job was still running. Requires: an indexed site URL from `ethora-sources-site-list-v2` (crawled with `ethora-sources-site-crawl-v2`). Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId` or `urlId`; 504/timeout if it takes longer than `timeoutMs` (the job may still complete server-side). Related: get `urlId` from `ethora-sources-site-list-v2`.

Parameters3

appId	string	optional	24-char hex appId the URL belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
urlId	string	required	Id of a previously crawled URL record. Get it from `ethora-sources-site-list-v2`.
timeoutMs	integer	optional	How long to poll for the reindex to finish, in milliseconds. Default 45000, chosen to stay under the ~60s request timeout most MCP clients enforce. Caps at 600000 (10 min) for clients that allow longer calls.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the URL belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "urlId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of a previously crawled URL record. Get it from `ethora-sources-site-list-v2`."
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 1000,
      "maximum": 600000,
      "description": "How long to poll for the reindex to finish, in milliseconds. Default 45000, chosen to stay under the ~60s request timeout most MCP clients enforce. Caps at 600000 (10 min) for clients that allow longer calls."
    }
  },
  "required": [
    "urlId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-site-list-v2

List an app's crawled website sources, including each source's id, URL, and current RAG tags. Their ids feed `ethora-sources-site-tags-update-v2`, `ethora-sources-site-delete-url-v2-batch`, and `ethora-sources-site-reindex-v2`. Requires: a selected app (`ethora-app-select`) or an explicit `appId`. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`; empty list if nothing has been crawled.

Parameters1

appId

string

optional

24-char hex appId to list sources for. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId to list sources for. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-site-tags-update-v2

Set the RAG retrieval tags on a crawled website source — replaces the source's tag set with the provided `tags` array (not additive; pass `[]` to clear all). Tags let the bot's `ragTags` narrow retrieval. Requires: an indexed site URL from `ethora-sources-site-list-v2` (crawled with `ethora-sources-site-crawl-v2`). Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId` or `sourceId`. Related: get `sourceId` from `ethora-sources-site-list-v2`; doc equivalent is `ethora-sources-docs-tags-update-v2`.

Parameters3

appId	string	optional	24-char hex appId the source belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
sourceId	string	required	Id of the crawled site source to tag. Get it from `ethora-sources-site-list-v2`.
tags	array	required	The complete desired tag set for this source (replaces any existing tags). Up to 50 tags; pass `[]` to clear all.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the source belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "sourceId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the crawled site source to tag. Get it from `ethora-sources-site-list-v2`."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "maxItems": 50,
      "description": "The complete desired tag set for this source (replaces any existing tags). Up to 50 tags; pass `[]` to clear all."
    }
  },
  "required": [
    "sourceId",
    "tags"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-site-delete-url-v2

Remove a single crawled URL from an app's RAG sources, matched by its exact url string (app-token / B2B variant of `ethora-sources-site-delete-url`). Deletes the source record and its embeddings; not reversible. Matches on the exact stored URL string. Requires: an indexed site URL from `ethora-sources-site-list-v2` (crawled with `ethora-sources-site-crawl-v2`). Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 `url` not a crawled source. Related: get the stored value from `ethora-sources-site-list-v2`; bulk-by-id is `ethora-sources-site-delete-url-v2-batch`.

Parameters2

appId	string	optional	24-char hex appId the URL belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
url	string	required	Exact crawled URL string to remove (must match what was stored — get it from `ethora-sources-site-list-v2`).

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the URL belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "url": {
      "type": "string",
      "minLength": 1,
      "description": "Exact crawled URL string to remove (must match what was stored — get it from `ethora-sources-site-list-v2`)."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-docs-upload-v2

Upload documents (1–5; PDF, text, etc.) into an app's RAG sources (app-token / B2B variant of `ethora-sources-docs-upload`). Async — content becomes queryable once indexing finishes; files passed as base64, 50MB max each. Requires: a selected app (`ethora-app-select`) or an explicit `appId`. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`; 413 too large; 422 unsupported document type. Related: `ethora-sources-docs-list-v2`, `ethora-sources-docs-delete-v2`.

Parameters2

appId	string	optional	24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
files	array	required	1 to 5 documents to ingest in this call.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId to ingest into. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Document file name including extension, e.g. `handbook.pdf`."
          },
          "mimeType": {
            "type": "string",
            "minLength": 1,
            "description": "MIME type, e.g. `application/pdf`, `text/plain`, `text/markdown`."
          },
          "base64": {
            "type": "string",
            "minLength": 1,
            "description": "Document content, base64-encoded. A `data:...;base64,` prefix is accepted. Max 50MB decoded per file."
          }
        },
        "required": [
          "name",
          "mimeType",
          "base64"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "1 to 5 documents to ingest in this call."
    }
  },
  "required": [
    "files"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-docs-list-v2

List an app's ingested documents, including each document's id, name, and current RAG tags. Their ids feed `ethora-sources-docs-tags-update-v2` and `ethora-sources-docs-delete-v2`. Requires: a selected app (`ethora-app-select`) or an explicit `appId`. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`; empty list if nothing has been uploaded. Related: website-sources equivalent is `ethora-sources-site-list-v2`.

Parameters1

appId

string

optional

24-char hex appId to list documents for. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId to list documents for. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-docs-tags-update-v2

Set the RAG retrieval tags on an ingested document — replaces the document's tag set with the provided `tags` array (not additive; pass `[]` to clear all). Tags let the bot's `ragTags` narrow retrieval. Requires: a document id from `ethora-sources-docs-list-v2`. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId` or `docId`. Related: get `docId` from `ethora-sources-docs-list-v2`; website-source equivalent is `ethora-sources-site-tags-update-v2`.

Parameters3

appId	string	optional	24-char hex appId the document belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
docId	string	required	Id of the ingested document to tag. Get it from `ethora-sources-docs-list-v2`.
tags	array	required	The complete desired tag set for this document (replaces any existing tags). Up to 50 tags; pass `[]` to clear all.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the document belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "docId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the ingested document to tag. Get it from `ethora-sources-docs-list-v2`."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "maxItems": 50,
      "description": "The complete desired tag set for this document (replaces any existing tags). Up to 50 tags; pass `[]` to clear all."
    }
  },
  "required": [
    "docId",
    "tags"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-docs-delete-v2

Remove a previously ingested document from an app's RAG sources by `docId` (app-token / B2B variant of `ethora-sources-docs-delete`). Deletes the document record and its embeddings; not reversible. Requires: a document id from `ethora-sources-docs-list-v2`. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId` or `docId`. Related: get `docId` from `ethora-sources-docs-list-v2`.

Parameters2

appId	string	optional	24-char hex appId the document belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
docId	string	required	Id of the ingested document to delete. Get it from `ethora-sources-docs-list-v2`.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the document belongs to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "docId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the ingested document to delete. Get it from `ethora-sources-docs-list-v2`."
    }
  },
  "required": [
    "docId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-users-batch-create-v2

Provision many Ethora users (1–100) in one asynchronous batch job — the bulk equivalent of `ethora-user-register`. Enqueues a background job (HTTP 202); the job reports per-user conflicts rather than failing the whole batch. Returns `{ jobId, statusUrl }`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode; 422 `usersList` validation. Related: track with `ethora-wait-users-batch-job-v2`.

Parameters3

bypassEmailConfirmation	boolean	optional	If true, created users skip email verification and are immediately usable. If false/omitted, each user receives a verification link.
usersList	array	required	The users to create, 1–100 per batch.
timeoutMs	integer	optional	HTTP timeout for the job-creation request (not the job itself), in milliseconds. Default 30000.

Raw schema

{
  "type": "object",
  "properties": {
    "bypassEmailConfirmation": {
      "type": "boolean",
      "description": "If true, created users skip email verification and are immediately usable. If false/omitted, each user receives a verification link."
    },
    "usersList": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "User's email address. Must be RFC-5322 valid."
          },
          "firstName": {
            "type": "string",
            "minLength": 1,
            "description": "User's first name, shown in their profile."
          },
          "lastName": {
            "type": "string",
            "minLength": 1,
            "description": "User's last name, shown in their profile."
          },
          "password": {
            "type": "string",
            "minLength": 1,
            "description": "Optional initial password. If omitted, the server generates one / relies on the verification flow."
          },
          "uuid": {
            "type": "string",
            "minLength": 1,
            "description": "Optional caller-supplied id to correlate this user with your own system in the job results."
          }
        },
        "required": [
          "email",
          "firstName",
          "lastName"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "The users to create, 1–100 per batch."
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 1000,
      "maximum": 600000,
      "description": "HTTP timeout for the job-creation request (not the job itself), in milliseconds. Default 30000."
    }
  },
  "required": [
    "usersList"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-users-batch-job-v2

Fetch the current status and per-user results of a users batch job by `jobId` (one-shot, no polling). Returns the job object with its `state` (pending/running/completed/failed) and per-user outcomes. Requires: a `jobId` returned by `ethora-users-batch-create-v2`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`) — must match the auth used to create the job. Errors: 401/403 not in B2B mode; 404 unknown `jobId`. Related: `ethora-wait-users-batch-job-v2` for a blocking wait.

Parameters2

jobId	string	required	Job id returned by `ethora-users-batch-create-v2`.
timeoutMs	integer	optional	HTTP timeout for this status request, in milliseconds. Default 10000.

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "minLength": 1,
      "description": "Job id returned by `ethora-users-batch-create-v2`."
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 500,
      "maximum": 60000,
      "description": "HTTP timeout for this status request, in milliseconds. Default 10000."
    }
  },
  "required": [
    "jobId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-wait-users-batch-job-v2

Block until a users batch job reaches a terminal state (`completed` or `failed`) or `timeoutMs` — read-only polling wrapper around `ethora-users-batch-job-v2`. Returns `{ done, state, job }`, or `{ done: false, reason: "timeout" }` on timeout. Requires: a `jobId` returned by `ethora-users-batch-create-v2`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`) — must match the auth used to create the job. Errors: 401/403 not in B2B mode; 404 unknown `jobId`.

Parameters3

jobId	string	required	Job id returned by `ethora-users-batch-create-v2`.
timeoutMs	integer	optional	Maximum time to wait, in milliseconds. Default 60000. Caps at 300000 (5 min).
intervalMs	integer	optional	Delay between status checks, in milliseconds. Default 1000.

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "minLength": 1,
      "description": "Job id returned by `ethora-users-batch-create-v2`."
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 1000,
      "maximum": 300000,
      "description": "Maximum time to wait, in milliseconds. Default 60000. Caps at 300000 (5 min)."
    },
    "intervalMs": {
      "type": "integer",
      "minimum": 250,
      "maximum": 10000,
      "description": "Delay between status checks, in milliseconds. Default 1000."
    }
  },
  "required": [
    "jobId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-tokens-list-v2

List the app tokens issued for an app — metadata only (`tokenId`, label, created/rotated timestamps, status); the secret token values are never returned (only shown once at create/rotate time). Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode; 400 no `appId` and none selected; 404 unknown `appId`.

Parameters2

appId	string	optional	24-char hex appId to list tokens for. Optional — defaults to the app set via `ethora-app-select`.
timeoutMs	integer	optional	HTTP timeout for this request, in milliseconds. Default 10000.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId to list tokens for. Optional — defaults to the app set via `ethora-app-select`."
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 500,
      "maximum": 60000,
      "description": "HTTP timeout for this request, in milliseconds. Default 10000."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-tokens-create-v2

Mint a new app token for an app. The secret token value is returned exactly once and cannot be retrieved again — capture it immediately. Returns the new token including its one-time secret value and `tokenId`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode; 400 no `appId` and none selected; 404 unknown `appId`. Related: manage with `ethora-app-tokens-list-v2` / `-rotate-v2` / `-revoke-v2`.

Parameters3

appId	string	optional	24-char hex appId to mint the token for. Optional — defaults to the app set via `ethora-app-select`.
label	string	optional	Human-readable label to identify this token later (e.g. `staging`, `ci`). Shown in `ethora-app-tokens-list-v2`.
timeoutMs	integer	optional	HTTP timeout for this request, in milliseconds. Default 10000.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId to mint the token for. Optional — defaults to the app set via `ethora-app-select`."
    },
    "label": {
      "type": "string",
      "description": "Human-readable label to identify this token later (e.g. `staging`, `ci`). Shown in `ethora-app-tokens-list-v2`."
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 500,
      "maximum": 60000,
      "description": "HTTP timeout for this request, in milliseconds. Default 10000."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-tokens-rotate-v2

Rotate an app token: revoke an existing token and issue a replacement in one step. The old `tokenId` is revoked immediately — anything using it stops working at once. The new secret value is returned exactly once — capture it immediately. Requires: a token id from `ethora-app-tokens-list-v2`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode; 400 no `appId` and none selected; 404 unknown `appId` or `tokenId`. Related: `ethora-app-tokens-revoke-v2` to revoke without a replacement.

Parameters4

appId	string	optional	24-char hex appId the token belongs to. Optional — defaults to the app set via `ethora-app-select`.
tokenId	string	required	Id of the token to revoke and replace. Get it from `ethora-app-tokens-list-v2`.
label	string	optional	Label for the replacement token. Omit to inherit the old token's label.
timeoutMs	integer	optional	HTTP timeout for this request, in milliseconds. Default 10000.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the token belongs to. Optional — defaults to the app set via `ethora-app-select`."
    },
    "tokenId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the token to revoke and replace. Get it from `ethora-app-tokens-list-v2`."
    },
    "label": {
      "type": "string",
      "description": "Label for the replacement token. Omit to inherit the old token's label."
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 500,
      "maximum": 60000,
      "description": "HTTP timeout for this request, in milliseconds. Default 10000."
    }
  },
  "required": [
    "tokenId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-tokens-revoke-v2

Permanently revoke an app token by `tokenId` — it stops working immediately; any client, SDK, or MCP session still using it gets auth failures. No replacement is issued. Requires: a token id from `ethora-app-tokens-list-v2`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode; 400 no `appId` and none selected; 404 unknown `appId`. Related: get `tokenId` from `ethora-app-tokens-list-v2`; `ethora-app-tokens-rotate-v2` for revoke-and-replace.

Parameters3

appId	string	optional	24-char hex appId the token belongs to. Optional — defaults to the app set via `ethora-app-select`.
tokenId	string	required	Id of the token to revoke. Get it from `ethora-app-tokens-list-v2`.
timeoutMs	integer	optional	HTTP timeout for this request, in milliseconds. Default 10000.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the token belongs to. Optional — defaults to the app set via `ethora-app-select`."
    },
    "tokenId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the token to revoke. Get it from `ethora-app-tokens-list-v2`."
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 500,
      "maximum": 60000,
      "description": "HTTP timeout for this request, in milliseconds. Default 10000."
    }
  },
  "required": [
    "tokenId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-b2b-app-provision

One-call B2B orchestrator: create an app, mint one or more app tokens, provision default chat rooms, then configure and enable its AI bot. Later-step failures don't undo earlier steps. Returns a per-step log including `appId` and the created tokens (returned once — capture them). Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: aborts with the partial step log if app creation fails; previous auth mode restored best-effort. Related: `ethora-b2b-app-bootstrap-ai` does sources+bot but not tokens/rooms.

Parameters10

displayName	string	required	Display name for the new app.
tokenLabels	array	optional	Labels for the app tokens to mint, one token per label. Default: ['default']. 1–5 tokens.
rooms	array	optional	Default chat rooms to create in the new app. Up to 20.
enableBot	boolean	optional	If true, enable the new app's bot using the first minted app token.
savedAgentId	string	optional	Optional id of an existing saved agent to bind as the new app's active bot, instead of setting prompt fields by hand.
botTrigger	string	optional	Bot trigger: `any_message` (every message) or `/bot` (only /bot-prefixed messages).
botPrompt	string	optional	System prompt for the new app's bot.
botGreetingMessage	string	optional	Greeting message the bot posts when a conversation starts.
llmProvider	string	optional	LLM provider for the bot, e.g. `openai` or `openai-compatible`. Must be enabled in your Ethora backend.
llmModel	string	optional	LLM model id for the bot, e.g. `gpt-4o-mini`. Must be available for the chosen provider.

Raw schema

{
  "type": "object",
  "properties": {
    "displayName": {
      "type": "string",
      "minLength": 1,
      "description": "Display name for the new app."
    },
    "tokenLabels": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "Labels for the app tokens to mint, one token per label. Default: ['default']. 1–5 tokens."
    },
    "rooms": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "description": "Display name of the room."
          },
          "pinned": {
            "type": "boolean",
            "description": "If true, add the room to the app's default rooms (new users auto-join)."
          }
        },
        "required": [
          "title"
        ],
        "additionalProperties": false
      },
      "maxItems": 20,
      "description": "Default chat rooms to create in the new app. Up to 20."
    },
    "enableBot": {
      "type": "boolean",
      "description": "If true, enable the new app's bot using the first minted app token."
    },
    "savedAgentId": {
      "type": "string",
      "description": "Optional id of an existing saved agent to bind as the new app's active bot, instead of setting prompt fields by hand."
    },
    "botTrigger": {
      "type": "string",
      "enum": [
        "any_message",
        "/bot"
      ],
      "description": "Bot trigger: `any_message` (every message) or `/bot` (only /bot-prefixed messages)."
    },
    "botPrompt": {
      "type": "string",
      "description": "System prompt for the new app's bot."
    },
    "botGreetingMessage": {
      "type": "string",
      "description": "Greeting message the bot posts when a conversation starts."
    },
    "llmProvider": {
      "type": "string",
      "description": "LLM provider for the bot, e.g. `openai` or `openai-compatible`. Must be enabled in your Ethora backend."
    },
    "llmModel": {
      "type": "string",
      "description": "LLM model id for the bot, e.g. `gpt-4o-mini`. Must be available for the chosen provider."
    }
  },
  "required": [
    "displayName"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-user-login

Authenticate as an existing Ethora user with email + password. Stores the user session token in this MCP session and unlocks user-auth tools (`ethora-app-list`, `ethora-files-*`, `ethora-wallet-*`). Auth: user-auth mode (`ethora-auth-use-user` first) and a configured `appJwt`. Errors: 401/403 bad credentials; 404 email not registered; 429 per-IP rate limit — retry with backoff.

Parameters5

email	string	required	User's registered email address (RFC 5322). Must match an account created via `ethora-user-register`.
password	string	required	Plain-text password the user set during registration. Sent over TLS to the Ethora API; never echoed back or logged.
createApiKey	boolean	optional	When true, also mint a long-lived API key for this user and return it once, so headless clients / agents can reconnect with `Authorization: Bearer <key>` instead of logging in again. Default false.
apiKeyName	string	optional	Label for the API key when `createApiKey` is true (e.g. `claude-code-laptop`).
apiKeyTtlDays	integer	optional	Lifetime of the API key in days when `createApiKey` is true. Server default applies when omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "User's registered email address (RFC 5322). Must match an account created via `ethora-user-register`."
    },
    "password": {
      "type": "string",
      "description": "Plain-text password the user set during registration. Sent over TLS to the Ethora API; never echoed back or logged."
    },
    "createApiKey": {
      "type": "boolean",
      "description": "When true, also mint a long-lived API key for this user and return it once, so headless clients / agents can reconnect with `Authorization: Bearer <key>` instead of logging in again. Default false."
    },
    "apiKeyName": {
      "type": "string",
      "description": "Label for the API key when `createApiKey` is true (e.g. `claude-code-laptop`)."
    },
    "apiKeyTtlDays": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "Lifetime of the API key in days when `createApiKey` is true. Server default applies when omitted."
    }
  },
  "required": [
    "email",
    "password"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-user-register

Create a new Ethora user account by email + first/last name, then log in and bind the session. A password is generated when omitted and returned once. By default also mints a long-lived API key so an agent can reconnect later with `Authorization: Bearer <key>` (no human step needed). Auth: user-auth mode and a configured `appJwt` (on a hosted server this is preset). Errors: 401 no `appJwt`; 422 email already registered or password shorter than 6 chars; 429 rate limited. Related: bulk provisioning uses `ethora-users-batch-create-v2`.

Parameters7

email	string	required	Email address for the new user. Must be RFC-5322 valid and not already registered within this app. No confirmation click is required to log in; the address is used for password reset.
firstName	string	required	First name shown in the user's profile and message attributions across chat rooms and the app UI.
lastName	string	required	Last name shown in the user's profile.
password	string	optional	Password for the account (min 6 chars). Omit to have a strong random password generated and returned once in the result.
createApiKey	boolean	optional	Mint a long-lived API key right after signup and return it once. Default true. Set false if you only need this session.
apiKeyName	string	optional	Label for the API key (default `mcp-signup`).
apiKeyTtlDays	integer	optional	API key lifetime in days. Server default applies when omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "Email address for the new user. Must be RFC-5322 valid and not already registered within this app. No confirmation click is required to log in; the address is used for password reset."
    },
    "firstName": {
      "type": "string",
      "description": "First name shown in the user's profile and message attributions across chat rooms and the app UI."
    },
    "lastName": {
      "type": "string",
      "description": "Last name shown in the user's profile."
    },
    "password": {
      "type": "string",
      "minLength": 6,
      "description": "Password for the account (min 6 chars). Omit to have a strong random password generated and returned once in the result."
    },
    "createApiKey": {
      "type": "boolean",
      "description": "Mint a long-lived API key right after signup and return it once. Default true. Set false if you only need this session."
    },
    "apiKeyName": {
      "type": "string",
      "description": "Label for the API key (default `mcp-signup`)."
    },
    "apiKeyTtlDays": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "API key lifetime in days. Server default applies when omitted."
    }
  },
  "required": [
    "email",
    "firstName",
    "lastName"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-api-key-create

Mint a long-lived, revocable API key for the currently logged-in user. The key is a user token: send it as `Authorization: Bearer <key>` to the hosted MCP endpoint (or set it in the stdio client) to skip `ethora-user-login`. Shown once. Auth: user auth (logged in). Errors: 401 not logged in; 404 on backends without API key support.

Parameters2

name	string	optional	Label to recognise the key later (e.g. `ci-runner`, `claude-desktop`).
ttlDays	integer	optional	Lifetime in days. Server default applies when omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Label to recognise the key later (e.g. `ci-runner`, `claude-desktop`)."
    },
    "ttlDays": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "Lifetime in days. Server default applies when omitted."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-api-key-list

List the current user's API keys (id, name, createdAt, expiresAt). Token values are never returned. Auth: user auth.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

ethora-api-key-revoke

Revoke one of the current user's API keys by id. Clients using that key stop working immediately. Requires: a key id from `ethora-api-key-list` or `ethora-api-key-create`. Auth: user auth. Errors: 404 unknown id.

Parameters1

string

required

API key id as returned by `ethora-api-key-create` / `ethora-api-key-list`.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "API key id as returned by `ethora-api-key-create` / `ethora-api-key-list`."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-credentials

Reveal the appToken of an app the caller owns, for a chat-component snippet or a widget config. Every other tool redacts appToken, appSecret and tenantSecret from its results because tool output enters the model's context and client logs; this tool returns exactly { appId, appToken, note } and nothing else. The App Secret is never returned over MCP: it is shown only in the web dashboard (app settings, API tab), and backend integrations should use revocable server tokens from that tab instead of the secret. Requires: an app you own (`ethora-app-create` or `ethora-app-list`) and `confirm: true`. Auth: user auth (app owner). Errors: 401 not logged in; 403 not the owner; 404 unknown `appId`; validation error unless `confirm` is `true`.

Parameters2

appId	string	optional	24-char hex app id. Defaults to the app selected with `ethora-app-select`.
confirm	boolean	required	Must be `true`: acknowledges that the token is a credential and will appear in this conversation.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex app id. Defaults to the app selected with `ethora-app-select`."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be `true`: acknowledges that the token is a credential and will appear in this conversation."
    }
  },
  "required": [
    "confirm"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-feedback-submit

Send feedback about Ethora to the Ethora team: something that does not work, behaves differently from what the tool description promised, is missing, or is badly documented. It reaches the team directly, so prefer it over guessing or silently giving up when a tool fails. Recent failures in this session (tool, error code, request id) are attached automatically when `includeRecentErrors` is true, which is what makes a report from here more useful than a web form: the team can join it to the server-side log. Works whether or not you are signed in, so a problem that blocks sign-up can still be reported. Do not put credentials, API keys or end-user personal data in `message`; credential-shaped values in the attached context are redacted before sending. Requires: nothing. Auth: none. Works anonymously; when the session is authenticated the report is attributed to that account. Errors: 422 if `message` is shorter than 5 characters or looks like spam; 429 if too many reports were sent from this address.

Parameters4

category	string	optional	What kind of report this is: `bug` (something is broken), `unexpected` (it works but not as described), `feature` (a request), `docs` (a description or guide is wrong or missing), `other`. Defaults to `other`.
message	string	required	What happened, in the user's own words where possible: what was attempted, what was expected, what occurred instead. No credentials or end-user personal data.
email	string	optional	Reply address. Only useful when the session is not signed in; an authenticated report already carries the account, so leave this out unless the user offers an address.
includeRecentErrors	boolean	optional	Attach this session's last few tool failures (tool name, error code, request id) so the team can trace them. Default true; set false if the report is unrelated to a failure.

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "bug",
        "unexpected",
        "feature",
        "docs",
        "other"
      ],
      "description": "What kind of report this is: `bug` (something is broken), `unexpected` (it works but not as described), `feature` (a request), `docs` (a description or guide is wrong or missing), `other`. Defaults to `other`."
    },
    "message": {
      "type": "string",
      "minLength": 5,
      "maxLength": 4000,
      "description": "What happened, in the user's own words where possible: what was attempted, what was expected, what occurred instead. No credentials or end-user personal data."
    },
    "email": {
      "type": "string",
      "description": "Reply address. Only useful when the session is not signed in; an authenticated report already carries the account, so leave this out unless the user offers an address."
    },
    "includeRecentErrors": {
      "type": "boolean",
      "description": "Attach this session's last few tool failures (tool name, error code, request id) so the team can trace them. Default true; set false if the report is unrelated to a failure."
    }
  },
  "required": [
    "message"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-widget-embed-snippet

Generate the <script> tag that embeds the Ethora AI chat widget (the floating launcher + chat panel that website visitors use) for an app, plus the prerequisites that must hold before it answers. No API call; pure generator using this deployment's hosted widget URL and public API base. The widget answers with the app's ACTIVE bot: for API-created apps run `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2 { agentId, chatJid }` first, otherwise `POST /v2/widget/sessions` returns 422 and the widget stays silent. Requires: an activated agent on the app (`ethora-agents-activate-v2`); without it the widget opens but never answers. Auth: none required (uses the selected app when `appId` is omitted). Errors: effectively none; when no hosted widget is configured the snippet carries a `<WIDGET_URL>` placeholder. Related: `ethora-agents-activate-v2`, `ethora-bot-widget-v2` (legacy per-app bot only).

Parameters10

appId	string	optional	App the widget belongs to (24-char hex). Defaults to the app from `ethora-app-select`.
botName	string	optional	Display name shown in the widget header (`data-bot-name`), e.g. the agent's name.
botAvatar	string	optional	Avatar image URL shown for the bot (`data-bot-avatar`).
botId	string	optional	Legacy `data-bot-id` (bot XMPP address); only for old embeds. Prefer `appId`: the backend picks the active agent from the app.
primaryColor	string	optional	Brand colour for launcher and bubbles (`data-primary-color`), e.g. `#0052CC`.
locale	string	optional	UI locale (`data-locale`), e.g. `en`, `fr`, `es`.
greeting	string	optional	Greeting shown when the panel opens (`data-greeting-message`).
position	string	optional	Launcher corner (`data-position`).
apiBase	string	optional	Override the public API base (`data-api-base`). Defaults to this deployment's public API URL.
widgetUrl	string	optional	Override the widget bundle base URL (the script is `<widgetUrl>/assistant.js`).

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "App the widget belongs to (24-char hex). Defaults to the app from `ethora-app-select`."
    },
    "botName": {
      "type": "string",
      "description": "Display name shown in the widget header (`data-bot-name`), e.g. the agent's name."
    },
    "botAvatar": {
      "type": "string",
      "description": "Avatar image URL shown for the bot (`data-bot-avatar`)."
    },
    "botId": {
      "type": "string",
      "description": "Legacy `data-bot-id` (bot XMPP address); only for old embeds. Prefer `appId`: the backend picks the active agent from the app."
    },
    "primaryColor": {
      "type": "string",
      "description": "Brand colour for launcher and bubbles (`data-primary-color`), e.g. `#0052CC`."
    },
    "locale": {
      "type": "string",
      "description": "UI locale (`data-locale`), e.g. `en`, `fr`, `es`."
    },
    "greeting": {
      "type": "string",
      "description": "Greeting shown when the panel opens (`data-greeting-message`)."
    },
    "position": {
      "type": "string",
      "enum": [
        "right",
        "left"
      ],
      "description": "Launcher corner (`data-position`)."
    },
    "apiBase": {
      "type": "string",
      "description": "Override the public API base (`data-api-base`). Defaults to this deployment's public API URL."
    },
    "widgetUrl": {
      "type": "string",
      "description": "Override the widget bundle base URL (the script is `<widgetUrl>/assistant.js`)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-list

List all Ethora apps (tenants) owned by the currently logged-in user. Returns an array with `appId` (24-char hex), `displayName`, `domainName`, ownership and bot-status metadata. Credential fields (appSecret, tenantSecret, appToken, passwords) are redacted in the result; call `ethora-app-credentials { appId, confirm: true }` to reveal an app's appToken. Auth: user-auth mode, active session (`ethora-user-login` first). Errors: 401 not logged in; empty list if the user owns no apps. Related: feed `appId` into `ethora-app-update` / `ethora-app-select`.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

ethora-app-create

Create a new Ethora app (tenant) owned by the currently logged-in user. Allocates a fresh 24-char hex `appId` and sets the caller as owner; counts against the owner's plan limit. Returns the new app object including `appId`. The returned app has its credential fields redacted; call `ethora-app-credentials { appId, confirm: true }` when a snippet needs the appToken. Auth: user-auth mode, active session (`ethora-user-login` first). Errors: 401 not logged in; 402/403 plan limit reached; 422 invalid `displayName`. Related: server-side provisioning uses `ethora-b2b-app-create`.

Parameters1

displayName

string

required

Human-readable app name shown to users in the app picker and on the public landing page. Not required to be unique across accounts.

Raw schema

{
  "type": "object",
  "properties": {
    "displayName": {
      "type": "string",
      "description": "Human-readable app name shown to users in the app picker and on the public landing page. Not required to be unique across accounts."
    }
  },
  "required": [
    "displayName"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-update

Update mutable fields on an app the caller owns (displayName, domainName, appTagline, primaryColor, botStatus). Partial update — omitted fields are left unchanged. Requires: an `appId` from `ethora-app-list` or `ethora-app-create`. Auth: user-auth mode, active session; the caller must own the app. Errors: 401 not logged in; 403 not owner; 404 unknown `appId`; 422 validation (e.g. `domainName` taken, `primaryColor` not `#RRGGBB`).

Parameters7

appId	string	optional	24-char hex ObjectId of the app to update. Optional — defaults to the app most recently passed to `ethora-app-select`.
displayName	string	optional	New human-readable app name. Visible in the app picker and on the public landing page.
domainName	string	optional	Subdomain to host the web app at. Setting `abcd` makes the web app available at `abcd.ethora.com`. Must be unique across all Ethora apps; lower-case alphanumerics and dashes only.
appTagline	string	optional	Short tagline shown on the public app landing page.
appDescription	string	optional	Deprecated alias for `appTagline`, kept so older callers keep working. Prefer `appTagline`.
primaryColor	string	optional	Primary brand color in hex `#RRGGBB` format (e.g. `#F54927`). Used throughout the app UI.
botStatus	string	optional	`on` enables the AI bot for new conversations (requires a configured prompt — see `ethora-bot-update-v2`); `off` disables it. Does not change the bot's configured prompt or sources.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex ObjectId of the app to update. Optional — defaults to the app most recently passed to `ethora-app-select`."
    },
    "displayName": {
      "type": "string",
      "description": "New human-readable app name. Visible in the app picker and on the public landing page."
    },
    "domainName": {
      "type": "string",
      "description": "Subdomain to host the web app at. Setting `abcd` makes the web app available at `abcd.ethora.com`. Must be unique across all Ethora apps; lower-case alphanumerics and dashes only."
    },
    "appTagline": {
      "type": "string",
      "description": "Short tagline shown on the public app landing page."
    },
    "appDescription": {
      "type": "string",
      "description": "Deprecated alias for `appTagline`, kept so older callers keep working. Prefer `appTagline`."
    },
    "primaryColor": {
      "type": "string",
      "description": "Primary brand color in hex `#RRGGBB` format (e.g. `#F54927`). Used throughout the app UI."
    },
    "botStatus": {
      "type": "string",
      "enum": [
        "on",
        "off"
      ],
      "description": "`on` enables the AI bot for new conversations (requires a configured prompt — see `ethora-bot-update-v2`); `off` disables it. Does not change the bot's configured prompt or sources."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-get-default-rooms

List the default chat rooms (MUC rooms) of the currently selected Ethora app — every new user auto-joins these. Returns rooms with their JIDs and titles. Auth: user-auth mode, active session; operates against the app set via `ethora-app-select`. Errors: 400 no app currently selected; 401 not logged in. Related: `ethora-app-get-default-rooms-with-app-id` to pass `appId` explicitly.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

ethora-app-create-chat

Create a new chat room (MUC room) inside an app the caller owns. Every room created this way is listed in the app's rooms (`defaultRooms`); `pinned: true` additionally makes new users auto-join it (existing users are not added), `pinned: false` (default) keeps it opt-in. Returns the new room object including its JID. Requires: a selected app (`ethora-app-select`) or an explicit `appId`. Auth: user-auth mode, active session; the caller must own the app. Errors: 401 not logged in; 403 not owner; 404 unknown `appId`; 422 invalid `title`.

Parameters3

appId	string	optional	24-char hex ObjectId of the app to create the chat room in. Optional — defaults to the app most recently passed to `ethora-app-select`.
title	string	required	Display name for the new chat room. Visible to all members; not required to be unique within the app.
pinned	boolean	optional	If `true`, the room is added to the app's default rooms list — every new user of the app auto-joins it. If `false`, the room exists but users must be added explicitly.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex ObjectId of the app to create the chat room in. Optional — defaults to the app most recently passed to `ethora-app-select`."
    },
    "title": {
      "type": "string",
      "description": "Display name for the new chat room. Visible to all members; not required to be unique within the app."
    },
    "pinned": {
      "type": "boolean",
      "default": false,
      "description": "If `true`, the room is added to the app's default rooms list — every new user of the app auto-joins it. If `false`, the room exists but users must be added explicitly."
    }
  },
  "required": [
    "title"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-delete-chat

Permanently delete a chat room from an app the caller owns — removes the MUC room, its message archive, and all member affiliations. Irreversible; gated behind ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true. Requires: a room from `ethora-app-get-default-rooms` or `ethora-app-create-chat`. Auth: user-auth mode, active session; the caller must own the app. Errors: 401 not logged in; 403 not owner; 404 `chatJid` not a room in the app.

Parameters2

appId	string	optional	24-char hex ObjectId of the app the chat room belongs to. Optional — defaults to the app most recently passed to `ethora-app-select`.
chatJid	string	required	Room JID (XMPP address) of the chat to delete, e.g. `<roomId>@conference.<host>`. Obtain from `ethora-app-get-default-rooms` or the response of `ethora-app-create-chat`.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex ObjectId of the app the chat room belongs to. Optional — defaults to the app most recently passed to `ethora-app-select`."
    },
    "chatJid": {
      "type": "string",
      "description": "Room JID (XMPP address) of the chat to delete, e.g. `<roomId>@conference.<host>`. Obtain from `ethora-app-get-default-rooms` or the response of `ethora-app-create-chat`."
    }
  },
  "required": [
    "chatJid"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-get-default-rooms-with-app-id

List the default chat rooms of a specific Ethora app, passed via `appId` (or the currently selected app). Returns rooms with their JIDs and titles. Requires: an `appId` from `ethora-app-list` or `ethora-app-create`. Auth: user-auth mode, active session; the caller needs read access (ownership or room membership). Errors: 400 no `appId` and none selected; 401 not logged in; 403 no read access; 404 unknown `appId`.

Parameters1

appId

string

optional

24-char hex ObjectId of the app whose default rooms you want to read. Optional — defaults to the app most recently passed to `ethora-app-select`.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex ObjectId of the app whose default rooms you want to read. Optional — defaults to the app most recently passed to `ethora-app-select`."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-delete

Permanently delete an Ethora app the caller owns — removes its chat rooms, files, indexed RAG sources, and bot config; end users are immediately signed out. Irreversible; gated behind ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true. Requires: an `appId` from `ethora-app-list` or `ethora-app-create`. Auth: user-auth mode, active session; the caller must own the app. Errors: 401 not logged in; 403 not owner; 404 unknown `appId`. Related: to just deactivate the bot use `ethora-app-update` with `botStatus: "off"`.

Parameters1

appId

string

required

24-char hex MongoDB ObjectId of the app to delete. Obtain from `ethora-app-list` or the response of `ethora-app-create`.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex MongoDB ObjectId of the app to delete. Obtain from `ethora-app-list` or the response of `ethora-app-create`."
    }
  },
  "required": [
    "appId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-sources-site-delete-url-v2-batch

Bulk-remove crawled website sources (1–100) from an app in one call, matched by their source record ids. Deletes each matching record and its embeddings; not reversible. Ids not present are skipped. Requires: an indexed site URL from `ethora-sources-site-list-v2` (crawled with `ethora-sources-site-crawl-v2`). Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`. Related: matches on source ids (not URL strings) — get them from `ethora-sources-site-list-v2`.

Parameters2

appId	string	optional	24-char hex appId the sources belong to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
ids	array	required	Site source record ids to delete, 1–100 per call. Get them from `ethora-sources-site-list-v2`.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the sources belong to. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "ids": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Site source record ids to delete, 1–100 per call. Get them from `ethora-sources-site-list-v2`."
    }
  },
  "required": [
    "ids"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agents-delete-v2

Delete an Agent (DELETE /v2/agents/:idOrAddress). Destructive — removes the saved Agent and its BotInstances. Gated behind ETHORA_MCP_ENABLE_DANGEROUS_TOOLS. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.

Parameters2

agentIdOrAddress	string	optional	Mongo _id (24 hex chars) or EOA-style address.
agentId	string	optional	Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1,
      "description": "Mongo _id (24 hex chars) or EOA-style address."
    },
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-b2b-app-create

Create a new Ethora app (tenant) server-side using B2B auth — the partner/integrator equivalent of `ethora-app-create`. Allocates a fresh 24-char hex `appId`; does not create tokens, rooms, or a bot. Returns the new app object including `appId`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`). Errors: 401/403 not in B2B mode or invalid `b2bToken`; 422 invalid `displayName`. Related: all-in-one path is `ethora-b2b-app-bootstrap-ai` / `ethora-b2b-app-provision`.

Parameters1

displayName

string

required

Human-readable app name shown to users in the app picker and on the public landing page.

Raw schema

{
  "type": "object",
  "properties": {
    "displayName": {
      "type": "string",
      "minLength": 1,
      "description": "Human-readable app name shown to users in the app picker and on the public landing page."
    }
  },
  "required": [
    "displayName"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-b2b-bot-enable

Enable the LEGACY per-app aiBot (B2B auth). NOTE: apps created via the API/B2B no longer auto-provision a legacy aiBot, so this returns 422 BOT_NOT_INITIALIZED on a clean app. The forward path for B2B AI is the Agents API — use `ethora-b2b-app-bootstrap-ai` or `ethora-agents-create-v2` + `ethora-agent-invite-to-chat`. This tool remains valid for apps that already have a legacy aiBot (e.g. admin-panel apps created with a default chat). Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead.

Parameters2

appId	string	optional	24-char hex appId whose bot to enable. Optional — defaults to the app set via `ethora-app-select`.
botTrigger	string	optional	When the bot responds: `/bot` (only messages starting with /bot) or `any_message` (every message). Omit to leave the existing trigger unchanged.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId whose bot to enable. Optional — defaults to the app set via `ethora-app-select`."
    },
    "botTrigger": {
      "type": "string",
      "description": "When the bot responds: `/bot` (only messages starting with /bot) or `any_message` (every message). Omit to leave the existing trigger unchanged."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-bot-get-v2

Read the current AI bot configuration for an app: status, trigger, prompt, greeting, LLM provider/model, RAG settings, widget config. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`. Related: change config with `ethora-bot-update-v2`.

Parameters1

appId

string

optional

24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode (the token determines the app).

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode (the token determines the app)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-bot-update-v2

Configure the AI bot for an app — prompt, LLM, trigger, greeting, RAG behavior, identity, and public widget settings. Partial update — omitted fields are left unchanged. `status: "on"` activates the bot (best-effort; needs a prompt + LLM and a backend AI service). Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`; 422 validation (e.g. an `llmProvider`/`llmModel` not enabled). Related: `ethora-bot-get-v2`, `ethora-agents-activate-v2`.

Parameters17

appId	string	optional	24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
status	string	optional	`on` activates the bot, `off` deactivates it. Omit to leave the current status unchanged.
savedAgentId	string	optional	Id of a saved agent whose config should back this bot. Alternative to setting prompt/LLM/RAG fields individually.
trigger	string	optional	When the bot responds: `any_message` (replies to every message) or `/bot` (only messages starting with /bot).
prompt	string	optional	System prompt that defines the bot's persona and behavior.
greetingMessage	string	optional	Message the bot posts when a conversation starts.
chatId	string	optional	Restrict the bot to a single chat by id. Omit to apply app-wide.
isRAG	boolean	optional	If true, the bot retrieves from the app's indexed RAG sources (see the `ethora-sources-*` tools) when answering.
botFirstName	string	optional	Bot's first name in its user profile.
botLastName	string	optional	Bot's last name in its user profile.
botDisplayName	string	optional	Bot's display name shown in chat.
botAvatarUrl	string	optional	Public URL of the bot's avatar image.
ragTags	array	optional	Restrict RAG retrieval to sources tagged with these tags (see `ethora-sources-site-tags-update-v2` / `ethora-sources-docs-tags-update-v2`).
llmProvider	string	optional	LLM provider, e.g. `openai` or `openai-compatible`. Must be enabled in your Ethora backend's AI service config.
llmModel	string	optional	LLM model id, e.g. `gpt-4o-mini`. Must be available for the chosen `llmProvider`.
widgetPublicEnabled	boolean	optional	If true, expose the bot through a public embeddable chat widget.
widgetPublicUrl	string	optional	Public URL for the embeddable widget. Usually read via `ethora-bot-widget-v2` rather than set here.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "status": {
      "type": "string",
      "enum": [
        "on",
        "off"
      ],
      "description": "`on` activates the bot, `off` deactivates it. Omit to leave the current status unchanged."
    },
    "savedAgentId": {
      "type": "string",
      "description": "Id of a saved agent whose config should back this bot. Alternative to setting prompt/LLM/RAG fields individually."
    },
    "trigger": {
      "type": "string",
      "enum": [
        "any_message",
        "/bot"
      ],
      "description": "When the bot responds: `any_message` (replies to every message) or `/bot` (only messages starting with /bot)."
    },
    "prompt": {
      "type": "string",
      "description": "System prompt that defines the bot's persona and behavior."
    },
    "greetingMessage": {
      "type": "string",
      "description": "Message the bot posts when a conversation starts."
    },
    "chatId": {
      "type": "string",
      "description": "Restrict the bot to a single chat by id. Omit to apply app-wide."
    },
    "isRAG": {
      "type": "boolean",
      "description": "If true, the bot retrieves from the app's indexed RAG sources (see the `ethora-sources-*` tools) when answering."
    },
    "botFirstName": {
      "type": "string",
      "description": "Bot's first name in its user profile."
    },
    "botLastName": {
      "type": "string",
      "description": "Bot's last name in its user profile."
    },
    "botDisplayName": {
      "type": "string",
      "description": "Bot's display name shown in chat."
    },
    "botAvatarUrl": {
      "type": "string",
      "description": "Public URL of the bot's avatar image."
    },
    "ragTags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Restrict RAG retrieval to sources tagged with these tags (see `ethora-sources-site-tags-update-v2` / `ethora-sources-docs-tags-update-v2`)."
    },
    "llmProvider": {
      "type": "string",
      "description": "LLM provider, e.g. `openai` or `openai-compatible`. Must be enabled in your Ethora backend's AI service config."
    },
    "llmModel": {
      "type": "string",
      "description": "LLM model id, e.g. `gpt-4o-mini`. Must be available for the chosen `llmProvider`."
    },
    "widgetPublicEnabled": {
      "type": "boolean",
      "description": "If true, expose the bot through a public embeddable chat widget."
    },
    "widgetPublicUrl": {
      "type": "string",
      "description": "Public URL for the embeddable widget. Usually read via `ethora-bot-widget-v2` rather than set here."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-bot-enable-v2

Enable the LEGACY per-app aiBot using app-token or B2B auth. NOTE: clean API/B2B-created apps have no legacy aiBot, so this returns 422 BOT_NOT_INITIALIZED there — use the Agents API (`ethora-agents-create-v2` + `ethora-agent-invite-to-chat`, or `ethora-b2b-app-bootstrap-ai`) for B2B AI. Valid for apps that already have a legacy aiBot. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead.

Parameters2

appId	string	optional	24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.
trigger	string	optional	When the bot responds: `any_message` (every message) or `/bot` (only /bot-prefixed messages). Omit to leave the existing trigger unchanged.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    },
    "trigger": {
      "type": "string",
      "enum": [
        "any_message",
        "/bot"
      ],
      "description": "When the bot responds: `any_message` (every message) or `/bot` (only /bot-prefixed messages). Omit to leave the existing trigger unchanged."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-bot-disable-v2

Turn the AI bot off for an app (sets bot `status: "off"`) — it stops responding. The configured prompt/LLM/RAG and any activated agent are preserved, so re-enabling restores the same behavior. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead. Auth: app-token mode OR B2B mode with an explicit `appId`. Errors: 401/403 wrong auth; 404 unknown `appId`. Related: `ethora-bot-enable-v2` to turn back on.

Parameters1

appId

string

optional

24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId. Required in B2B mode unless already set via `ethora-app-select`; ignored in app-token mode."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-bot-widget-v2

LEGACY: read the per-app bot widget config (`GET /v2/bot/widget`); only apps that already have a legacy aiBot have one, API-created apps get 422. For the embeddable AI chat widget use `ethora-widget-embed-snippet` instead — the widget config and public widget URL metadata needed to embed the bot on a website. Requires: an app with a legacy per-app aiBot (dashboard-created). API-created apps have none: use `ethora-agents-create-v2` -> `ethora-agent-invite-to-chat` -> `ethora-agents-activate-v2` instead. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 not in app-token mode or invalid appToken. Related: enable/disable via `widgetPublicEnabled` in `ethora-bot-update-v2`.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

ethora-agents-list-v2

List the reusable saved agents of an app (`GET /v2/apps/:appId/agents`, or `GET /v2/agents` for the token's own app) — a saved agent is a reusable bot definition. Returns an array of agents with ids, names, and config. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 not in app-token mode or invalid appToken; empty list if the app has no saved agents.

Parameters1

appId

string

optional

24-char hex appId whose agents to list (`GET /v2/apps/:appId/agents`). Defaults to the app selected with `ethora-app-select`; without either, lists the agents of the token's own app.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId whose agents to list (`GET /v2/apps/:appId/agents`). Defaults to the app selected with `ethora-app-select`; without either, lists the agents of the token's own app."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agents-get-v2

Fetch one reusable saved agent's full config by id (`GET /v2/agents/:agentId`) — prompt, LLM, RAG settings, visibility. Also sets this agent as the session's current agent context (no server-side change). Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 wrong auth; 404 `agentId` not an agent of the current app. Related: get ids from `ethora-agents-list-v2`.

Parameters2

agentId	string	optional	Id of the saved agent to fetch. Get it from `ethora-agents-list-v2`.
agentIdOrAddress	string	optional	Alias for `agentId` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the saved agent to fetch. Get it from `ethora-agents-list-v2`."
    },
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentId` - either name is accepted, pass whichever you have."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agents-create-v2

Create a reusable AI agent (POST /v2/apps/:appId/agents). Works in user auth mode (the normal hosted mode) or B2B mode; app-token mode is not accepted by the backend. Each agent is a persona — name, avatar, system prompt, LLM config, plus response-gate settings (responseMode, cooldownSec) that control when it speaks in a room. For multi-agent scenarios (two or more personas conversing in one chat) create each one separately, then `ethora-agent-invite-to-chat` them into the same room. See the `ethora-agents-quickstart` prompt for the end-to-end recipe. Requires: a selected app (`ethora-app-select`) or an explicit `appId`; the agent is owned by that app.

Parameters20

appId	string	optional	24-char hex appId the agent belongs to (`POST /v2/apps/:appId/agents`). Defaults to the app selected with `ethora-app-select`. Pass it when you just created an app so the agent lands there rather than in the token's own app.
name	string	optional	Short display name. For multi-agent scenarios, prefer single-word names (e.g. 'Hannibal', 'Varro') — the @-mention matcher uses the exact display name with word-boundary matching.
slug	string	optional	URL-safe slug (auto-generated from name if omitted).
summary	string	optional	Short bio shown in agent lists.
prompt	string	optional	System prompt — the agent's persona, role, style of speech, and behaviour rules. For multi-agent scenarios, instruct the agent to end every message with an @-mention of who speaks next; that's how turn-handoff works through the response gate.
greetingMessage	string	optional	Optional message the agent posts when it first joins a room.
trigger	string	optional	Legacy trigger field. Prefer the newer `responseMode` for new agents.
responseMode	string	optional	When the agent decides to reply. 'always' = every room message; 'mentioned' = only when @-mentioned by display name or via /bot (recommended for multi-agent turn-taking); 'smart' = a mini LLM gate decides per-message; 'probability' = coin-flip per message using `responseProbability`.
responseProbability	number	optional	If responseMode='probability', odds (0-1) of replying to each message. Damped 0.6x for bot-to-bot messages.
cooldownSec	integer	optional	Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking in multi-agent scenarios.
botDisplayName	string	optional	Display name used inside the chat UI. Defaults to `name`.
botAvatarUrl	string	optional	URL of the avatar image shown next to bot messages.
isRAG	boolean	optional	Enable retrieval-augmented generation from indexed sources.
ragTags	array	optional	Optional RAG tag filter — restrict retrieval to sources matching these tags.
llmProvider	string	optional	LLM provider override (e.g. 'openai'). Defaults to the app's configured provider.
llmModel	string	optional	LLM model override (e.g. 'gpt-4o-mini').
visibility	string	optional	'private' (only invitable inside the owning app) or 'public' (cross-app invitable).
isPublished	boolean	optional	Convenience alias for setting visibility='public'.
categories	array	optional	Free-form category tags for agent directory listings.
flowsYaml	string	optional	Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn to the model. Compiled and validated server-side on save: an invalid script is rejected with code `FLOWS_INVALID` and per-line details, and nothing is stored. A flow named `start` is reserved and fires when a conversation opens. Buttons are authored here (`buttons:` on a `say` step, or `options:` on an `ask` step). Call `fetch` with id `doc:agent-flows` for the full authoring format before writing one. Pass an empty string to clear the script.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "24-char hex appId the agent belongs to (`POST /v2/apps/:appId/agents`). Defaults to the app selected with `ethora-app-select`. Pass it when you just created an app so the agent lands there rather than in the token's own app."
    },
    "name": {
      "type": "string",
      "description": "Short display name. For multi-agent scenarios, prefer single-word names (e.g. 'Hannibal', 'Varro') — the @-mention matcher uses the exact display name with word-boundary matching."
    },
    "slug": {
      "type": "string",
      "description": "URL-safe slug (auto-generated from name if omitted)."
    },
    "summary": {
      "type": "string",
      "description": "Short bio shown in agent lists."
    },
    "prompt": {
      "type": "string",
      "description": "System prompt — the agent's persona, role, style of speech, and behaviour rules. For multi-agent scenarios, instruct the agent to end every message with an @-mention of who speaks next; that's how turn-handoff works through the response gate."
    },
    "greetingMessage": {
      "type": "string",
      "description": "Optional message the agent posts when it first joins a room."
    },
    "trigger": {
      "type": "string",
      "enum": [
        "any_message",
        "/bot"
      ],
      "description": "Legacy trigger field. Prefer the newer `responseMode` for new agents."
    },
    "responseMode": {
      "type": "string",
      "enum": [
        "always",
        "mentioned",
        "smart",
        "probability"
      ],
      "description": "When the agent decides to reply. 'always' = every room message; 'mentioned' = only when @-mentioned by display name or via /bot (recommended for multi-agent turn-taking); 'smart' = a mini LLM gate decides per-message; 'probability' = coin-flip per message using `responseProbability`."
    },
    "responseProbability": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "If responseMode='probability', odds (0-1) of replying to each message. Damped 0.6x for bot-to-bot messages."
    },
    "cooldownSec": {
      "type": "integer",
      "minimum": 0,
      "description": "Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking in multi-agent scenarios."
    },
    "botDisplayName": {
      "type": "string",
      "description": "Display name used inside the chat UI. Defaults to `name`."
    },
    "botAvatarUrl": {
      "type": "string",
      "description": "URL of the avatar image shown next to bot messages."
    },
    "isRAG": {
      "type": "boolean",
      "description": "Enable retrieval-augmented generation from indexed sources."
    },
    "ragTags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Optional RAG tag filter — restrict retrieval to sources matching these tags."
    },
    "llmProvider": {
      "type": "string",
      "description": "LLM provider override (e.g. 'openai'). Defaults to the app's configured provider."
    },
    "llmModel": {
      "type": "string",
      "description": "LLM model override (e.g. 'gpt-4o-mini')."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ],
      "description": "'private' (only invitable inside the owning app) or 'public' (cross-app invitable)."
    },
    "isPublished": {
      "type": "boolean",
      "description": "Convenience alias for setting visibility='public'."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Free-form category tags for agent directory listings."
    },
    "flowsYaml": {
      "type": "string",
      "description": "Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn to the model. Compiled and validated server-side on save: an invalid script is rejected with code `FLOWS_INVALID` and per-line details, and nothing is stored. A flow named `start` is reserved and fires when a conversation opens. Buttons are authored here (`buttons:` on a `say` step, or `options:` on an `ask` step). Call `fetch` with id `doc:agent-flows` for the full authoring format before writing one. Pass an empty string to clear the script."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agents-update-v2

Update a saved AI agent (PUT /v2/agents/:agentId). All fields are optional — only what you pass is updated. Common uses: tune the system `prompt` after a test run, switch `responseMode` to control turn-taking in multi-agent rooms, or adjust `cooldownSec`. See `ethora-agents-quickstart` prompt for the end-to-end recipe. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.

Parameters21

agentId	string	optional	Mongo _id (24 hex chars) of the agent to update.
name	string	optional	New display name. For multi-agent scenarios prefer single-word names — the @-mention matcher uses exact display-name match with word-boundary.
slug	string	optional	URL-safe slug.
summary	string	optional	Short bio.
prompt	string	optional	Updated system prompt (persona + behaviour). For multi-agent rooms instruct the agent to end every message with an @-mention of the next speaker — that's how turn-handoff works through the response gate.
greetingMessage	string	optional	Message the agent posts when it first joins a new room.
trigger	string	optional	Legacy trigger field. Prefer `responseMode`.
responseMode	string	optional	When the agent replies. 'always' = every message; 'mentioned' = only @-mention or /bot (best for multi-agent turn-taking); 'smart' = mini-LLM decides; 'probability' = coin-flip using `responseProbability`.
responseProbability	number	optional	If responseMode='probability', odds (0-1) of replying. Damped 0.6x for bot-to-bot.
cooldownSec	integer	optional	Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking.
botDisplayName	string	optional	Display name in chat UI.
botAvatarUrl	string	optional	Avatar image URL.
isRAG	boolean	optional	Enable RAG retrieval.
ragTags	array	optional	RAG tag filter.
llmProvider	string	optional	LLM provider override.
llmModel	string	optional	LLM model override.
visibility	string	optional	'private' or 'public' (cross-app invitable).
isPublished	boolean	optional	Convenience alias for visibility='public'.
categories	array	optional	Category tags for directory listings.
flowsYaml	string	optional	Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn to the model. Compiled and validated server-side on save: an invalid script is rejected with code `FLOWS_INVALID` and per-line details, and nothing is stored. A flow named `start` is reserved and fires when a conversation opens. Buttons are authored here (`buttons:` on a `say` step, or `options:` on an `ask` step). Call `fetch` with id `doc:agent-flows` for the full authoring format before writing one. Pass an empty string to clear the script.
agentIdOrAddress	string	optional	Alias for `agentId` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Mongo _id (24 hex chars) of the agent to update."
    },
    "name": {
      "type": "string",
      "description": "New display name. For multi-agent scenarios prefer single-word names — the @-mention matcher uses exact display-name match with word-boundary."
    },
    "slug": {
      "type": "string",
      "description": "URL-safe slug."
    },
    "summary": {
      "type": "string",
      "description": "Short bio."
    },
    "prompt": {
      "type": "string",
      "description": "Updated system prompt (persona + behaviour). For multi-agent rooms instruct the agent to end every message with an @-mention of the next speaker — that's how turn-handoff works through the response gate."
    },
    "greetingMessage": {
      "type": "string",
      "description": "Message the agent posts when it first joins a new room."
    },
    "trigger": {
      "type": "string",
      "enum": [
        "any_message",
        "/bot"
      ],
      "description": "Legacy trigger field. Prefer `responseMode`."
    },
    "responseMode": {
      "type": "string",
      "enum": [
        "always",
        "mentioned",
        "smart",
        "probability"
      ],
      "description": "When the agent replies. 'always' = every message; 'mentioned' = only @-mention or /bot (best for multi-agent turn-taking); 'smart' = mini-LLM decides; 'probability' = coin-flip using `responseProbability`."
    },
    "responseProbability": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "If responseMode='probability', odds (0-1) of replying. Damped 0.6x for bot-to-bot."
    },
    "cooldownSec": {
      "type": "integer",
      "minimum": 0,
      "description": "Minimum seconds between this agent's replies in a given room. Damped 2x for bot-to-bot. Set 0 for quick turn-taking."
    },
    "botDisplayName": {
      "type": "string",
      "description": "Display name in chat UI."
    },
    "botAvatarUrl": {
      "type": "string",
      "description": "Avatar image URL."
    },
    "isRAG": {
      "type": "boolean",
      "description": "Enable RAG retrieval."
    },
    "ragTags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "RAG tag filter."
    },
    "llmProvider": {
      "type": "string",
      "description": "LLM provider override."
    },
    "llmModel": {
      "type": "string",
      "description": "LLM model override."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ],
      "description": "'private' or 'public' (cross-app invitable)."
    },
    "isPublished": {
      "type": "boolean",
      "description": "Convenience alias for visibility='public'."
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Category tags for directory listings."
    },
    "flowsYaml": {
      "type": "string",
      "description": "Deterministic scripted conversation for this agent, as YAML. Drives the agent through a fixed sequence (opening menu, appointment request, intake questionnaire, survey) instead of leaving every turn to the model. Compiled and validated server-side on save: an invalid script is rejected with code `FLOWS_INVALID` and per-line details, and nothing is stored. A flow named `start` is reserved and fires when a conversation opens. Buttons are authored here (`buttons:` on a `say` step, or `options:` on an `ask` step). Call `fetch` with id `doc:agent-flows` for the full authoring format before writing one. Pass an empty string to clear the script."
    },
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentId` - either name is accepted, pass whichever you have."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agents-clone-v2

Duplicate an existing saved agent into a new agent, optionally overriding its name/slug/summary (`POST /v2/agents/:agentId/clone`). The source agent is unchanged; the new clone becomes the session's current agent context. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`. Auth: app-token mode (after `ethora-app-select` + `ethora-auth-use-app`). Errors: 401/403 wrong auth; 404 source `agentId` not found; 422 overridden `slug` collides.

Parameters5

agentId	string	optional	Id of the source agent to clone. Get it from `ethora-agents-list-v2`.
name	string	optional	Name for the clone. Omit to inherit the source agent's name.
slug	string	optional	URL-safe unique slug for the clone. Omit to let the server derive one; must not collide with an existing agent.
summary	string	optional	Summary for the clone. Omit to inherit the source agent's summary.
agentIdOrAddress	string	optional	Alias for `agentId` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Id of the source agent to clone. Get it from `ethora-agents-list-v2`."
    },
    "name": {
      "type": "string",
      "description": "Name for the clone. Omit to inherit the source agent's name."
    },
    "slug": {
      "type": "string",
      "description": "URL-safe unique slug for the clone. Omit to let the server derive one; must not collide with an existing agent."
    },
    "summary": {
      "type": "string",
      "description": "Summary for the clone. Omit to inherit the source agent's summary."
    },
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentId` - either name is accepted, pass whichever you have."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agents-activate-v2

Make an agent the app's ACTIVE widget bot: sets `App.defaultBotInstanceId` (and `botStatus: on`), which is what `POST /v2/widget/sessions` uses to decide who answers website visitors. Required before an embedded widget can answer on an API-created app. Preconditions: the agent was invited into a room of this app with `ethora-agent-invite-to-chat` (that creates its bot instance). Works in user auth (app update route); falls back to the app-token `/v2/agents/:id/activate` route when an appToken is stored. Requires: an agent already invited into a room of the selected app (`ethora-agents-create-v2` -> `ethora-app-create-chat` -> `ethora-agent-invite-to-chat`); the invite creates the bot instance this tool binds as the app's default responder. Auth: user session (owner of the app). Errors: 404 no bot instance for this agent in the app (invite first); 403 not the app owner. Related: `ethora-widget-embed-snippet` next, `ethora-bot-instances-list` to inspect.

Parameters4

agentId	string	optional	Id (or address) of the agent to activate. Get it from `ethora-agents-list-v2` / `ethora-agents-create-v2`.
chatJid	string	optional	Room JID `${appId}_${chatId}` (with or without `@conference...`) that becomes the widget chat. Required for API-created apps; omit only for dashboard-created apps that already have an AI Widget chat bound.
appId	string	optional	App to activate the agent for. Defaults to the app from `ethora-app-select`.
agentIdOrAddress	string	optional	Alias for `agentId` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Id (or address) of the agent to activate. Get it from `ethora-agents-list-v2` / `ethora-agents-create-v2`."
    },
    "chatJid": {
      "type": "string",
      "description": "Room JID `${appId}_${chatId}` (with or without `@conference...`) that becomes the widget chat. Required for API-created apps; omit only for dashboard-created apps that already have an AI Widget chat bound."
    },
    "appId": {
      "type": "string",
      "description": "App to activate the agent for. Defaults to the app from `ethora-app-select`."
    },
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentId` - either name is accepted, pass whichever you have."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agent-set-visibility

Set an Agent's visibility (private | unlisted | public). Public agents can be invited cross-app by anyone who knows the address. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.

Parameters3

agentIdOrAddress	string	optional
visibility	string	required
agentId	string	optional	Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ]
    },
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have."
    }
  },
  "required": [
    "visibility"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agent-invite-to-chat

Invite an Agent into a chat room. Multiple agents can coexist in the same room — call this tool once per agent and they will all appear as members able to converse. Lazily creates a per-App BotInstance (an Ethora user with isBot:true) if one does not already exist for (agent, app). Spawns the XMPP client live; no ai-service restart required. For the full multi-agent recipe see the `ethora-agents-quickstart` prompt. Requires: an agent (`ethora-agents-create-v2`) and a room (`ethora-app-create-chat`) in the selected app.

Parameters5

agentIdOrAddress	string	optional	Either Mongo _id (24 hex chars) or EOA-style address.
appId	string	optional	Required in B2B mode unless already selected via ethora-app-select.
chatId	string	optional	Mongo Chat _id (preferred when invoking from admin).
chatJid	string	optional	Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`), exactly the `jid` returned by `ethora-app-create-chat`. Preferred over `chatId`.
agentId	string	optional	Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1,
      "description": "Either Mongo _id (24 hex chars) or EOA-style address."
    },
    "appId": {
      "type": "string",
      "description": "Required in B2B mode unless already selected via ethora-app-select."
    },
    "chatId": {
      "type": "string",
      "description": "Mongo Chat _id (preferred when invoking from admin)."
    },
    "chatJid": {
      "type": "string",
      "description": "Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`), exactly the `jid` returned by `ethora-app-create-chat`. Preferred over `chatId`."
    },
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agent-soul-append

Append a fragment to an Agent's SOUL.MD (its evolving identity / private notes). Operator-driven; the Agent itself can also self-edit via the same endpoint when called by ai-service. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.

Parameters3

agentIdOrAddress	string	optional
append	string	required
agentId	string	optional	Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1
    },
    "append": {
      "type": "string",
      "minLength": 1
    },
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have."
    }
  },
  "required": [
    "append"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agent-soul-set

Replace an Agent's SOUL.MD with the provided markdown. Operator-driven; alternative to -append. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.

Parameters3

agentIdOrAddress	string	optional
soulMd	string	required	Replace SOUL.MD contents. Pass empty string to clear.
agentId	string	optional	Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1
    },
    "soulMd": {
      "type": "string",
      "minLength": 0,
      "description": "Replace SOUL.MD contents. Pass empty string to clear."
    },
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have."
    }
  },
  "required": [
    "soulMd"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-bot-instances-list

List BotInstances. Filter by appId (caller's App by default) and/or agentId. Requires: at least one invited agent in the app (`ethora-agent-invite-to-chat`); otherwise the list is empty.

Parameters3

appId	string	optional
agentId	string	optional
agentIdOrAddress	string	optional	Alias for `agentId` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string"
    },
    "agentId": {
      "type": "string"
    },
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentId` - either name is accepted, pass whichever you have."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-bot-instance-status

Turn a specific BotInstance on or off. Off detaches it from XMPP; on re-spawns the XMPP client live. Requires: a bot instance id from `ethora-bot-instances-list` (instances are created by `ethora-agent-invite-to-chat`).

Parameters2

botInstanceId	string	required
status	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "botInstanceId": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "on",
        "off"
      ]
    }
  },
  "required": [
    "botInstanceId",
    "status"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agents-export-v2

Export an Agent as a portable bundle (GET /v2/agents/:idOrAddress/export). format=json returns the bundle object directly; feed it back to `ethora-agents-import-v2` to recreate the Agent in another App/tenant. Requires: an agent id or address from `ethora-agents-list-v2` or `ethora-agents-create-v2`.

Parameters3

agentIdOrAddress	string	optional
format	string	optional	Defaults to json. Prefer json for MCP round-trips.
agentId	string	optional	Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1
    },
    "format": {
      "type": "string",
      "enum": [
        "json",
        "zip"
      ],
      "description": "Defaults to json. Prefer json for MCP round-trips."
    },
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-agents-import-v2

Import an Agent from a bundle produced by `ethora-agents-export-v2` (POST /v2/agents/import, application/json body IS the bundle). Optionally scope the new Agent to an owning App via ownerAppId. Requires: a bundle produced by `ethora-agents-export-v2` with format json.

Parameters2

bundle	object	required	The bundle object returned by `ethora-agents-export-v2` with format=json. Pass it through unchanged.
ownerAppId	string	optional	Owning App for the imported Agent (defaults server-side).

Raw schema

{
  "type": "object",
  "properties": {
    "bundle": {
      "type": "object",
      "properties": {
        "schemaVersion": {
          "type": "string",
          "minLength": 1,
          "description": "Bundle schema version, e.g. `ethora.agent.bundle.v1`. Every export carries one."
        },
        "kind": {
          "type": "string",
          "description": "Bundle kind: `agent` for agent exports."
        },
        "agent": {
          "type": "object",
          "additionalProperties": {},
          "description": "The agent definition carried by the bundle: displayName, prompt, llmProvider, llmModel and so on."
        }
      },
      "required": [
        "schemaVersion",
        "agent"
      ],
      "additionalProperties": true,
      "description": "The bundle object returned by `ethora-agents-export-v2` with format=json. Pass it through unchanged."
    },
    "ownerAppId": {
      "type": "string",
      "description": "Owning App for the imported Agent (defaults server-side)."
    }
  },
  "required": [
    "bundle"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-bot-instance-diag

Diagnose a specific BotInstance for an Agent (GET /v2/agents/:idOrAddress/bot-instances/:botInstanceId/diag). Returns live XMPP/ai-service status and recent activity for troubleshooting. Requires: a bot instance id from `ethora-bot-instances-list` (instances are created by `ethora-agent-invite-to-chat`).

Parameters3

agentIdOrAddress	string	optional
botInstanceId	string	required
agentId	string	optional	Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1
    },
    "botInstanceId": {
      "type": "string",
      "minLength": 1
    },
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have."
    }
  },
  "required": [
    "botInstanceId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-bot-instance-test-message

Send a test message from a BotInstance (POST /v2/agents/:idOrAddress/bot-instances/:botInstanceId/test-message). Omit roomJid to fan out to every room the BotInstance is in. Requires the ai-service to be running. Requires: a bot instance id from `ethora-bot-instances-list` (instances are created by `ethora-agent-invite-to-chat`).

Parameters5

agentIdOrAddress	string	optional
botInstanceId	string	required
text	string	optional	Message body. Optional/empty is allowed.
roomJid	string	optional	Target a specific room JID; omit to broadcast to all the bot's rooms.
agentId	string	optional	Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1
    },
    "botInstanceId": {
      "type": "string",
      "minLength": 1
    },
    "text": {
      "type": "string",
      "maxLength": 2000,
      "description": "Message body. Optional/empty is allowed."
    },
    "roomJid": {
      "type": "string",
      "description": "Target a specific room JID; omit to broadcast to all the bot's rooms."
    },
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have."
    }
  },
  "required": [
    "botInstanceId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-bot-instance-leave-chat

Remove a BotInstance from a chat room (POST /v2/agents/:idOrAddress/bot-instances/:botInstanceId/leave-chat). The inverse of `ethora-agent-invite-to-chat`. Requires: a bot instance id from `ethora-bot-instances-list` (instances are created by `ethora-agent-invite-to-chat`).

Parameters4

agentIdOrAddress	string	optional
botInstanceId	string	required
chatJid	string	required	Fully-qualified room JID to leave.
agentId	string	optional	Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have.

Raw schema

{
  "type": "object",
  "properties": {
    "agentIdOrAddress": {
      "type": "string",
      "minLength": 1
    },
    "botInstanceId": {
      "type": "string",
      "minLength": 1
    },
    "chatJid": {
      "type": "string",
      "minLength": 1,
      "description": "Fully-qualified room JID to leave."
    },
    "agentId": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `agentIdOrAddress` - either name is accepted, pass whichever you have."
    }
  },
  "required": [
    "botInstanceId",
    "chatJid"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-messages-search-v2

Search an App's chat messages (GET /v2/apps/:appId/messages/search). B2B / tenant-actor auth. Filter by room (chatId), author (fromUserId), and time window. Requires: a selected app (`ethora-app-select`) or an explicit `appId`.

Parameters10

q	string	required	Search query.
appId	string	optional	Required in B2B mode unless already selected via ethora-app-select.
mode	string	optional
chatId	string	optional
fromUserId	string	optional
since	string	optional	ISO date lower bound.
until	string	optional	ISO date upper bound.
sort	string	optional
limit	integer	optional
offset	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Search query."
    },
    "appId": {
      "type": "string",
      "description": "Required in B2B mode unless already selected via ethora-app-select."
    },
    "mode": {
      "type": "string",
      "enum": [
        "substring",
        "fulltext"
      ]
    },
    "chatId": {
      "type": "string"
    },
    "fromUserId": {
      "type": "string"
    },
    "since": {
      "type": "string",
      "description": "ISO date lower bound."
    },
    "until": {
      "type": "string",
      "description": "ISO date upper bound."
    },
    "sort": {
      "type": "string",
      "enum": [
        "relevance",
        "date"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "q"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-messages-context-v2

Fetch the messages surrounding a target message (GET /v2/apps/:appId/chats/:chatId/messages/context). Provide either aroundStanzaId or aroundMessageId; radius controls how many messages before/after. Requires: a message id from `ethora-messages-search-v2` or `ethora-chats-history-v2`.

Parameters5

chatId	string	required
appId	string	optional	Required in B2B mode unless already selected via ethora-app-select.
aroundStanzaId	string	optional
aroundMessageId	string	optional
radius	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "chatId": {
      "type": "string",
      "minLength": 1
    },
    "appId": {
      "type": "string",
      "description": "Required in B2B mode unless already selected via ethora-app-select."
    },
    "aroundStanzaId": {
      "type": "string"
    },
    "aroundMessageId": {
      "type": "string"
    },
    "radius": {
      "type": "integer",
      "minimum": 0,
      "maximum": 50
    }
  },
  "required": [
    "chatId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-unread-counts-v2

Batch per-room unread message counts for a set of users (POST /v2/apps/:appId/users/unread-counts). mode=count returns numbers (capped); mode=flag returns booleans. Requires Mongo message archiving enabled on the deployment. Requires: a selected app (`ethora-app-select`) or an explicit `appId`.

Parameters5

userIds	array	required	uuid / Mongo _id / xmppUsername, 1..200.
appId	string	optional	Required in B2B mode unless already selected via ethora-app-select.
mode	string	optional
cap	integer	optional
concurrency	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "userIds": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "uuid / Mongo _id / xmppUsername, 1..200."
    },
    "appId": {
      "type": "string",
      "description": "Required in B2B mode unless already selected via ethora-app-select."
    },
    "mode": {
      "type": "string",
      "enum": [
        "count",
        "flag"
      ]
    },
    "cap": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "concurrency": {
      "type": "integer",
      "minimum": 1,
      "maximum": 32
    }
  },
  "required": [
    "userIds"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-export-v2

Export an App as a portable bundle (GET /v2/apps/:appId/export). format=json returns the bundle object directly. Use `include` to select sections (e.g. 'chats,users,sources,botInstances'). Feed the result to `ethora-app-import-v2`. Requires: a selected app (`ethora-app-select`) or an explicit `appId`.

Parameters3

appId	string	optional	Required in B2B mode unless already selected via ethora-app-select.
format	string	optional
include	string	optional	Comma-separated sections to include, e.g. 'chats,users,sources,botInstances'.

Raw schema

{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string",
      "description": "Required in B2B mode unless already selected via ethora-app-select."
    },
    "format": {
      "type": "string",
      "enum": [
        "json",
        "zip"
      ]
    },
    "include": {
      "type": "string",
      "description": "Comma-separated sections to include, e.g. 'chats,users,sources,botInstances'."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-app-import-v2

Import an App from a bundle produced by `ethora-app-export-v2` (POST /v2/apps/import, application/json body IS the bundle). B2B / tenant-actor auth. domainNameOverride renames the imported App's domain. Requires: a bundle produced by `ethora-app-export-v2`.

Parameters2

bundle	any	optional	The exported bundle object (the json export output).
domainNameOverride	string	optional	Rename the imported App's domainName.

Raw schema

{
  "type": "object",
  "properties": {
    "bundle": {
      "description": "The exported bundle object (the json export output)."
    },
    "domainNameOverride": {
      "type": "string",
      "description": "Rename the imported App's domainName."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-chats-message-v2

Post a message into a chat room of an app (POST /v2/apps/:appId/chats/broadcast targeting one room). The message is attributed to the app's broadcast sender (override the shown name with `senderName`). Use it to seed or test a conversation, e.g. right after `ethora-agent-invite-to-chat`, and set `waitForReplySec` (up to 60) to wait for an AI agent's answer; replies are returned in `replies`. Identify the room by `roomJid` (`${appId}_${chatId}`, exactly what `ethora-app-create-chat` returns as `jid`) or by the bare `chatId` plus the selected app. Requires: a room in the selected app (`ethora-app-create-chat`); for `replies`, an agent invited into it (`ethora-agent-invite-to-chat`). Auth: user auth (the default on the hosted server) or B2B; app-token mode is not accepted by this route. Errors: 401 not logged in; 403 not the app owner; 404 unknown app/room; 422 empty text. Reply detection needs the message archive (MAM) on the deployment; when it is unavailable `replies` is null and `historyUnavailable` is true.

Parameters6

text	string	required	Message body to post (1-4000 chars).
roomJid	string	optional	Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`), as returned by `ethora-app-create-chat`. Either this or `chatId` is required.
chatId	string	optional	Chat id: either the Mongo chat `_id` (as listed by the app's chat list) or the suffix after `${appId}_` in the room JID. Needs an app: pass `appId` or select one with `ethora-app-select`.
appId	string	optional	24-char hex appId. Optional when `roomJid` carries it or an app is selected.
senderName	string	optional	Display name shown as the message sender (defaults to the app's broadcast sender / app name).
waitForReplySec	integer	optional	Seconds to wait for a reply from someone else in the room (an AI agent, typically). 0 (default) returns right after posting.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Message body to post (1-4000 chars)."
    },
    "roomJid": {
      "type": "string",
      "description": "Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`), as returned by `ethora-app-create-chat`. Either this or `chatId` is required."
    },
    "chatId": {
      "type": "string",
      "description": "Chat id: either the Mongo chat `_id` (as listed by the app's chat list) or the suffix after `${appId}_` in the room JID. Needs an app: pass `appId` or select one with `ethora-app-select`."
    },
    "appId": {
      "type": "string",
      "description": "24-char hex appId. Optional when `roomJid` carries it or an app is selected."
    },
    "senderName": {
      "type": "string",
      "maxLength": 60,
      "description": "Display name shown as the message sender (defaults to the app's broadcast sender / app name)."
    },
    "waitForReplySec": {
      "type": "integer",
      "minimum": 0,
      "maximum": 60,
      "description": "Seconds to wait for a reply from someone else in the room (an AI agent, typically). 0 (default) returns right after posting."
    }
  },
  "required": [
    "text"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-chats-history-v2

Read the archived messages of a chat room (GET /v2/apps/:appId/chats/:chatId/messages, newest last). Returns `results` with `from`, `nick`, `body`, `ts` (ms) plus a `nextBefore` cursor for older pages. Identify the room by `roomJid` (`${appId}_${chatId}`) or bare `chatId` plus the selected app. Requires: a room in the selected app (`ethora-app-create-chat`). Auth: user auth (default on the hosted server) or B2B; app-token mode is not accepted. Errors: 401 not logged in; 403 not the app owner; 404 unknown app/room; 502 MAM_READ_FAILED or `mamUnavailable: true` when the deployment has no message archive.

Parameters5

roomJid	string	optional	Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`). Either this or `chatId` is required.
chatId	string	optional	Bare chat id. Needs an app: pass `appId` or select one with `ethora-app-select`.
appId	string	optional	24-char hex appId. Optional when `roomJid` carries it or an app is selected.
limit	integer	optional	Maximum number of most-recent messages to return (default 100).
before	integer	optional	Pagination cursor: only messages older than this timestamp (ms), from a previous `nextBefore`.

Raw schema

{
  "type": "object",
  "properties": {
    "roomJid": {
      "type": "string",
      "description": "Room JID `${appId}_${chatId}` (optionally with `@conference.<host>`). Either this or `chatId` is required."
    },
    "chatId": {
      "type": "string",
      "description": "Bare chat id. Needs an app: pass `appId` or select one with `ethora-app-select`."
    },
    "appId": {
      "type": "string",
      "description": "24-char hex appId. Optional when `roomJid` carries it or an app is selected."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Maximum number of most-recent messages to return (default 100)."
    },
    "before": {
      "type": "integer",
      "minimum": 0,
      "description": "Pagination cursor: only messages older than this timestamp (ms), from a previous `nextBefore`."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-b2b-app-bootstrap-ai

One-call B2B orchestrator: create an app, set it as the current context, index RAG sources, then configure and enable its AI bot. Source ingest and bot activation are best-effort (the app is still created if a later step fails); crawl/embedding continues asynchronously after this returns. Returns a per-step log including the new `appId`. Auth: B2B mode (`ethora-auth-use-b2b` + a configured `b2bToken`); internally switches to app-token mode for source-ingest steps. Errors: aborts with the partial step log if app creation fails; previous auth mode restored best-effort. Related: rooms+tokens variant is `ethora-b2b-app-provision`.

Parameters14

displayName	string	required	Display name for the new app.
setAsCurrent	boolean	optional	If true (default), set the new app as the session's current app and switch to app-token auth so follow-up tools can omit appId.
crawlUrl	string	optional	Optional website URL to crawl and index into the new app's RAG sources.
followLink	boolean	optional	For `crawlUrl`: also follow in-domain links (default true). Can ingest many pages.
docs	array	optional	Optional docs to ingest (base64)
savedAgentId	string	optional	Optional saved agent to bind as the active bot for the new app.
enableBot	boolean	optional	If true, enables botStatus=on (best-effort AI service activation)
botTrigger	string	optional	Optional bot trigger (e.g. '/bot' or 'any_message')
llmProvider	string	optional	Optional generation provider for the default AI bot (example: 'openai' or 'openai-compatible').
llmModel	string	optional	Optional generation model for the default AI bot (example: 'gpt-4o-mini').
agentDisplayName	string	optional	Phase 1: create a new Agent with this display name as part of bootstrap.
agentPrompt	string	optional	Phase 1: persona/instructions for the newly-created Agent.
agentVisibility	string	optional	Phase 1: visibility for the newly-created Agent.
inviteToDefaultRoom	boolean	optional	Phase 1: if true (default), invite the newly-created Agent into the App's first default room.

Raw schema

{
  "type": "object",
  "properties": {
    "displayName": {
      "type": "string",
      "minLength": 1,
      "description": "Display name for the new app."
    },
    "setAsCurrent": {
      "type": "boolean",
      "description": "If true (default), set the new app as the session's current app and switch to app-token auth so follow-up tools can omit appId."
    },
    "crawlUrl": {
      "type": "string",
      "description": "Optional website URL to crawl and index into the new app's RAG sources."
    },
    "followLink": {
      "type": "boolean",
      "description": "For `crawlUrl`: also follow in-domain links (default true). Can ingest many pages."
    },
    "docs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "mimeType": {
            "type": "string",
            "minLength": 1
          },
          "base64": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "name",
          "mimeType",
          "base64"
        ],
        "additionalProperties": false
      },
      "description": "Optional docs to ingest (base64)"
    },
    "savedAgentId": {
      "type": "string",
      "description": "Optional saved agent to bind as the active bot for the new app."
    },
    "enableBot": {
      "type": "boolean",
      "description": "If true, enables botStatus=on (best-effort AI service activation)"
    },
    "botTrigger": {
      "type": "string",
      "description": "Optional bot trigger (e.g. '/bot' or 'any_message')"
    },
    "llmProvider": {
      "type": "string",
      "description": "Optional generation provider for the default AI bot (example: 'openai' or 'openai-compatible')."
    },
    "llmModel": {
      "type": "string",
      "description": "Optional generation model for the default AI bot (example: 'gpt-4o-mini')."
    },
    "agentDisplayName": {
      "type": "string",
      "description": "Phase 1: create a new Agent with this display name as part of bootstrap."
    },
    "agentPrompt": {
      "type": "string",
      "description": "Phase 1: persona/instructions for the newly-created Agent."
    },
    "agentVisibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ],
      "description": "Phase 1: visibility for the newly-created Agent."
    },
    "inviteToDefaultRoom": {
      "type": "boolean",
      "description": "Phase 1: if true (default), invite the newly-created Agent into the App's first default room."
    }
  },
  "required": [
    "displayName"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-generate-chat-component-app-tsx

Generate a ready-to-paste React `App.tsx` snippet that mounts `@ethora/chat-component`. Returns `{ filename: "App.tsx", snippet }`; unpassed values are emitted as placeholders. Does not write any file. Get the appToken from `ethora-app-credentials { appId, confirm: true }` (other tools redact it). Auth: none required — pure code generator, no API calls. Errors: effectively none. Security note: the snippet includes `appToken` inline only as a quickstart convenience — do not ship hardcoded tokens to production.

Parameters3

apiUrl	string	optional	Ethora API base URL to embed in the snippet, e.g. `https://api.chat.ethora.com/v1`. Omit to emit a placeholder.
appToken	string	optional	appToken to embed in the snippet for quickstart testing. Omit to emit a placeholder. Do NOT hardcode real tokens in production source.
roomJid	string	optional	Room JID to open on load. Omit to emit a commented-out placeholder.

Raw schema

{
  "type": "object",
  "properties": {
    "apiUrl": {
      "type": "string",
      "description": "Ethora API base URL to embed in the snippet, e.g. `https://api.chat.ethora.com/v1`. Omit to emit a placeholder."
    },
    "appToken": {
      "type": "string",
      "description": "appToken to embed in the snippet for quickstart testing. Omit to emit a placeholder. Do NOT hardcode real tokens in production source."
    },
    "roomJid": {
      "type": "string",
      "description": "Room JID to open on load. Omit to emit a commented-out placeholder."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-generate-env-examples

Generate `.env.example` templates for the three common Ethora integration targets: the frontend chat component, the backend SDK, and this MCP server. Returns `{ target, template }` when `target` is given, or `{ templates }` with all three. Placeholder values only; does not write any file. Auth: none required — pure text generator, no API calls. Errors: effectively none.

Parameters1

target

string

optional

Which template to return: `frontend-chat-component` (Vite env), `backend-sdk` (@ethora/sdk-backend env), or `mcp` (this server's env). Omit to return all three.

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "enum": [
        "frontend-chat-component",
        "backend-sdk",
        "mcp"
      ],
      "description": "Which template to return: `frontend-chat-component` (Vite env), `backend-sdk` (@ethora/sdk-backend env), or `mcp` (this server's env). Omit to return all three."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ethora-generate-b2b-bootstrap-runbook

Generate a human-readable runbook listing this server's tool calls in the right order for a B2B bootstrap, with example payloads. Documentation only — does not write any file or execute any step. Auth: none required — pure text generator, no API calls. Errors: effectively none. Related: to actually run the sequence use `ethora-run-recipe` or `ethora-b2b-app-bootstrap-ai`.

Parameters3

apiUrl	string	optional	Ethora API base URL to show in the runbook's configure step. Omit to emit a placeholder.
displayName	string	optional	App display name to show in the runbook's create-app step. Omit to emit a placeholder.
crawlUrl	string	optional	Website URL to show in the runbook's source-ingest step. Omit to emit a placeholder.

Raw schema

{
  "type": "object",
  "properties": {
    "apiUrl": {
      "type": "string",
      "description": "Ethora API base URL to show in the runbook's configure step. Omit to emit a placeholder."
    },
    "displayName": {
      "type": "string",
      "description": "App display name to show in the runbook's create-app step. Omit to emit a placeholder."
    },
    "crawlUrl": {
      "type": "string",
      "description": "Website URL to show in the runbook's source-ingest step. Omit to emit a placeholder."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search

Search the Ethora documentation and tool reference: auth model (app JWT vs app token vs B2B token vs API keys), hosted-server getting started, chat-component and backend SDK quickstarts, recipes, and a reference entry for every tool with its inputs. Use it for any "how do I ..." question about Ethora before guessing; then call `fetch` with a result id to read the full text. Auth: none required.

Parameters1

query

string

required

Free-text query, e.g. 'create an app', 'invite agent to chat', 'api key bearer header'. Empty returns the getting-started guides.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free-text query, e.g. 'create an app', 'invite agent to chat', 'api key bearer header'. Empty returns the getting-started guides."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

fetch

Fetch the full text of a documentation section or tool reference entry by the id returned from `search` (e.g. `tool:ethora-app-create`, `doc:auth-map#app-jwt`, `doc:hosted-guide`). Auth: none required. Errors: unknown id.

Parameters1

string

required

Document id from a `search` result.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Document id from a `search` result."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md38 KBView on GitHub

Ethora MCP Server (Model Context Protocol)

Add the hosted server in one click. You sign in through your browser; there is nothing to install and no key to paste.

For Claude.ai, ChatGPT, Claude Desktop, LM Studio and anything else that takes a connector URL, add https://mcp.chat.ethora.com/mcp/oauth and sign in. Running it yourself instead? See Using with stdio clients.

The MCP server for Ethora, an open-source chat and messaging platform with a built-in AI agent framework. It lets Claude, ChatGPT, Cursor, Claude Code, VS Code and autonomous agents create Ethora apps, chat rooms, users and AI agents, post messages, index RAG sources and produce website chat-widget embeds, all through tool calls.

Part of the Ethora SDK ecosystem. Cross-SDK updates: Release Notes. Package changes: CHANGELOG.md.

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

Three ways to use it

	Where it runs	Best for
Hosted (Ethora Cloud)	`https://mcp.chat.ethora.com/mcp` (production; `https://mcp.chat-qa.ethora.com/mcp` is the QA instance)	Claude.ai, ChatGPT, Claude Code, Cursor and agents that talk to Ethora Cloud with no local install
Self-hosted	Ships with the Ethora monoserver deploy; enable `services.mcp.enabled` in `deploy.yml` and it is served at `mcp.<your domain>/mcp`	Dedicated or on-premise Ethora installs; agent traffic never leaves your infrastructure
stdio CLI	`npx -y @ethora/mcp-server` on your machine, configured with env vars	Local development, CI, and clients that launch a command

The hosted and self-hosted modes are the same server started with ETHORA_MCP_TRANSPORT=http. Every MCP session has private in-memory state: one client's login, selected app or tokens are never visible to another session.

60-second quickstart

Claude.ai or ChatGPT (custom connector). In the Ethora web app open Account, then the AI Assistants tab, create an API key and copy the personal connector URL it shows (https://mcp.chat.ethora.com/mcp/k/<key>). Paste it as a custom connector. Every conversation is authenticated with no login step. For a listed connector that uses the vendor's OAuth login instead, the URL is https://mcp.chat.ethora.com/mcp/oauth.

Claude Code.

bash

# 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, and any client that takes a URL and headers.

json

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

Autonomous agents with no account yet. Connect to https://mcp.chat.ethora.com/mcp with no credentials and call ethora-user-register with an email, first and last name. It creates the account, logs the session in, and returns a generated password plus an API key and connectorUrl exactly once. Store the key and reconnect later with the Bearer header or the personal URL; nothing else is needed, no browser and no email confirmation.

stdio CLI.

bash

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

Then ask your agent to call ethora-status, ethora-user-login (or ethora-user-register) and ethora-app-list. Lost at any point, call ethora-help: it reads the current state and returns the recommended next calls.

Entry points and authentication

Entry point	Who supplies identity	Typical client
`/mcp` (add `?tools=all` to list every tool up front)	Nobody at connect time. Call `ethora-user-login` or `ethora-user-register` inside the session, or send `Authorization: Bearer <token>` on every request (user API key, app token or B2B token; the server picks the auth mode from the token type)	Agents, Claude Code, Cursor, connectors added as "no auth"
`/mcp/k/<api-key>`	The key in the path, applied like a Bearer header	Claude.ai and ChatGPT custom connectors, which take a URL but no headers
`/mcp/oauth`	An OAuth 2.1 access token obtained through the Ethora authorization server (dynamic client registration, PKCE, access scopes `read`, `write`, `admin`, plus the identity scopes `openid` and `email` for directories that require them)	Connector directories (Claude, ChatGPT); vendors run the login flow themselves
stdio	Env vars `ETHORA_APP_JWT` (login/register bootstrap) and optional `ETHORA_B2B_TOKEN`, or `ethora-session-configure` at runtime	Local CLI

Stay in user auth mode on the hosted server (ethora-status shows authMode: user). App-token and B2B modes exist for server integrations; the agents and rooms routes reject app tokens.

API keys

ethora-api-key-create { name?, ttlDays? } mints a key (default 90 days, max 365), shown once together with connectorUrl. ethora-user-register mints one by default and ethora-user-login { createApiKey: true } on request.
ethora-api-key-list shows id, name, created and expiry, never the value. ethora-api-key-revoke { id } invalidates it immediately: the next request with that key fails with REFRESH_RECORD_NOT_FOUND.
The same keys are managed in the Ethora web app under Account, AI Assistants, where the personal URL, a Claude Code one-liner and a Cursor config are shown with copy buttons.
A key acts as the user. Treat the personal URL like a password: do not share screenshots of it, revoke it if it leaks. The server never logs request URLs, and the monoserver nginx template logs method and status only on the MCP host.

OAuth 2.1 (`/mcp/oauth`)

Set ETHORA_MCP_AUTH_ISSUER to the public URL of the Ethora API that hosts the authorization server (the monoserver deploy sets it). The MCP server then:

serves RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp/oauth, naming the authorization server and the three scopes;
answers unauthenticated requests on /mcp/oauth with 401 and WWW-Authenticate: Bearer resource_metadata="...", which is how clients discover the flow;
validates each token against the API once per session (cached five minutes) and enforces the token's scope per tool: read-only tools need read, destructive tools need admin, everything else needs write. search, fetch, ethora-help, ethora-status and ethora-doctor need no scope. Tokens without a scope claim (API keys) get full access;
hides the identity tools (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) because the token already fixes who you are.

The authorization server itself is part of the Ethora backend: <issuer>/.well-known/oauth-authorization-server, /oauth/register, /oauth/authorize (a consent page with sign-in, account creation and Google sign-in), /oauth/token, /oauth/revoke and /oauth/userinfo. Users see and disconnect OAuth grants under Account, AI Assistants, Connected AI apps. When ETHORA_MCP_AUTH_ISSUER is unset, both OAuth routes return 404 and discovery omits them.

Identity scopes. Some directories (ChatGPT) require the minimal OpenID Connect surface on top of OAuth 2.1: the openid and email scopes and a userinfo endpoint that returns sub, email and email_verified. These scopes grant no access to apps or data; they only let the client see who signed in, and the consent page says so in plain words. There are no ID tokens or JWKS, because nothing consumes them.

Email confirmation is optional. Ethora never blocks sign-up or the dashboard on a confirmed address. When a client asks for the identity scopes and the account's address is not yet confirmed, the consent page adds one step: send the confirmation link, continue after confirming, or continue without sharing the address (the identity scopes are dropped from the grant and everything else proceeds). Google sign-ins arrive confirmed and skip the step. The same confirmation can be sent from Account, AI Assistants in the web app.

What agents can do

The end-to-end journey a new user typically asks for, with the tools in order:

ethora-user-register (or ethora-user-login) to get an authenticated session and an API key.
ethora-app-create { displayName } then ethora-app-select { appId } to make the new app current.
ethora-chat-create { title } to create a group room. The result contains the room JID ${appId}_${chatId}; every room tool accepts the JID or the bare chatId.
ethora-agent-create { name, prompt, ... } to create an AI agent persona in that app.
ethora-agent-invite { agentIdOrAddress, chatJid } to put the agent in the room. A bot instance is spawned live, no restart needed.
ethora-message-send { text, roomJid, waitForReplySec: 45 } to post a message and wait for the agent's answer, returned as replies. ethora-chat-history reads the room afterwards.
ethora-agent-activate { agentId, chatJid } to make that agent the app's default responder, then ethora-widget-snippet-get for the <script> tag that puts the AI chat widget on a website.

ethora-help { goal } returns this and the other recipes (user-login, broadcast, sources-ingest, files-upload, bot-manage, chat-test, widget, b2b-bootstrap-ai) with the calls filled in for the current state, and ethora-recipe-run executes them.

First-minute conventions

Every create tool answers the same way. ethora-app-create, ethora-chat-create, ethora-agent-create return the raw API object plus created (kind, id, name, and jid or address where relevant) and next, two to four suggested calls with arguments filled in. ethora-app-create also returns dashboardUrl, the app in the web dashboard.
ethora-help { goal } has a recipe for each headline job: new-app, in-app-chat, multi-agent-room, widget, chat-test, plus the server-integration goals. Each returns the calls in order with arguments to copy.
Who spoke. ethora-message-send replies and ethora-chat-history rows carry senderName and senderKind (human, agent, app), so a multi-agent room reads as "Freud: ..., Jung: ..." rather than instance ids.
Search understands intent. search maps the phrases people use ("add chat to my React app", "several agents talking to each other", "webhook when a message arrives") to the documents that answer them, and doc:not-available says plainly what is not exposed over MCP and where it lives instead. Whole documents are fetchable by their bare id (doc:recipes, doc:chat-component-quickstart, doc:sdk-backend-quickstart, doc:auth-map).

Documentation inside the server

instructions in the initialize result tell the assistant how identity works on the entry point it connected through: the open endpoint explains login and register, personal-URL and Bearer sessions are told they are already authenticated and must never ask for a password or key, OAuth sessions the same plus how to react to INSUFFICIENT_SCOPE.
search { query } and fetch { id } (the ChatGPT connector convention) search an in-memory corpus: the auth map, quickstarts, recipes, a hosted getting-started guide, an API keys guide and one reference entry per tool with its inputs. They work unauthenticated.
Resources ethora://docs/auth-map, ethora://docs/chat-component/quickstart, ethora://docs/sdk-backend/quickstart, ethora://docs/recipes and prompts ethora-auth-map, ethora-vite-quickstart, ethora-nextjs-quickstart, ethora-backend-sdk-quickstart, ethora-recipes, ethora-agents-quickstart.

Tool groups

A session lists the core group only at first: 24 tools covering the whole "sign in, create an app, add rooms and messages, create and activate an agent, give it a knowledge base, get the widget" journey, one variant per operation. The other groups are registered but hidden, which keeps tools/list around 40 KB instead of 120 KB and gives assistants a short list to choose from.

Three ways to get more:

ethora-tools-enable { group } enables a group for the session (or { group: "all" }); the server sends tools/list_changed and the client refreshes. With no arguments it returns the catalogue with counts.
Calling a hidden tool by name enables its group and runs it, so a name learned from the docs or an earlier session is never refused.
?tools=all on the endpoint URL (hosted) or ETHORA_MCP_TOOLS=all (stdio) lists everything up front.

search and fetch describe hidden tools too; every tool doc names its group, and doc:tool-groups is the catalogue. Legacy and async variants carry a first line naming the preferred sibling.

Group	What it covers	Tools
`core` (listed by default)	Sign in or register, create an app, add rooms and messages, create and activate an AI agent, give it a knowledge base, get the website widget. Always listed.	`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`	List and revoke API keys, reveal an app's credentials, mint and rotate app tokens.	`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`	Diagnostics, recipes and switching the session's auth mode (app token, B2B token) for server integrations.	`ethora-doctor`, `ethora-recipe-run`, `ethora-session-configure`, `ethora-auth-mode-set`, `ethora-auth-mode-set`, `ethora-auth-mode-set`
`apps-admin`	Delete, export and import whole apps; inspect default rooms.	`ethora-app-delete`, `ethora-app-export`, `ethora-app-import`, `ethora-app-rooms-list`, `ethora-app-rooms-list`
`rooms`	Delete rooms, broadcast to many rooms, search messages, read message context and unread counts.	`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`	Inspect, clone, delete, export and import agents; edit an agent's soul and visibility.	`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`	Knowledge-base maintenance: async crawl and reindex jobs, list and tag sites and documents, delete URLs and documents.	`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`	Batch-create users and upload, fetch or delete files.	`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`	The per-app bot of apps created in the dashboard before the agents framework, and the pre-v2 document tools. Prefer the agents and sources tools for anything new.	`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`	Server-to-server provisioning with a B2B token, plus code and config generators for integrations.	`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`	Wallet balance and ERC-20 transfer. Local (stdio) only; never offered on the hosted server.	`ethora-wallet-balance-get`, `ethora-wallet-erc20-transfer`

App deletion and bulk-delete tools are only registered when ETHORA_MCP_ENABLE_DANGEROUS_TOOLS=true (the monoserver deploy sets it; the stdio default is off). Alias tools (ethora.b2b.*, ethora-bot-message-send, ethora-bot-history) are off by default (ETHORA_MCP_ENABLE_ALIASES=true to expose them); the canonical tools cover the same ground.

ethora-widget-snippet-get returns the tag for the embeddable AI chat widget:

html

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

The widget answers with the app's active bot (defaultBotInstanceId). On an app created through the API run ethora-agent-create, ethora-chat-create, ethora-agent-invite and ethora-agent-activate { agentId, chatJid } first; the tool lists these prerequisites and ethora-help { goal: "widget" } walks through them. Activation runs in user auth by setting the app's default bot instance (what the admin AI Widget dropdown does). Until a bot is active, the widget's session endpoint answers AI_BOT_NOT_CONFIGURED. ethora-chat-component-app-generate produces a React App.tsx for @ethora/chat-component instead.

Configuration

Env vars (stdio and hosted)

Variable	Meaning
`ETHORA_API_URL`	Full API URL, e.g. `https://api.chat.ethora.com/v1` (default). On a hosted server it is fixed for all sessions
`ETHORA_BASE_URL`	Host-only alternative to `ETHORA_API_URL`; `/v1` is appended
`ETHORA_APP_JWT`	App JWT used only by login and register (`ETHORA_APP_TOKEN` is a legacy alias)
`ETHORA_APP_DOMAIN_NAME`	Base app `domainName`; when `ETHORA_APP_JWT` is empty the server fetches the app JWT from `GET /v1/apps/get-config?domainName=...` at startup
`ETHORA_B2B_TOKEN`	B2B server token for `x-custom-token` tenant-actor routes
`ETHORA_MCP_TOOLS`	`all` lists every tool from the start instead of the core group (stdio; hosted uses `?tools=all` on the URL)
`ETHORA_MCP_ENABLE_DANGEROUS_TOOLS`	`true` registers app deletion, wallet transfer and bulk-delete tools (default off)
`ETHORA_MCP_OPENAI_APPS_CHALLENGE`	Hosted only. Token issued by the OpenAI apps portal for domain verification; served verbatim at `/.well-known/openai-apps-challenge` (404 when unset)
`ETHORA_MCP_ENABLE_ALIASES`	`true` exposes the dot-namespaced alias tools (default off)

Hosted mode only

Variable	Meaning
`ETHORA_MCP_TRANSPORT`	`stdio` (default) or `http`; `--http` on the command line does the same
`ETHORA_MCP_HTTP_HOST`, `ETHORA_MCP_HTTP_PORT`	Bind address, default `127.0.0.1:3030`; put nginx in front
`ETHORA_MCP_PUBLIC_URL`	Public base URL advertised in discovery and used for `connectorUrl`, e.g. `https://mcp.chat.ethora.com/mcp`
`ETHORA_MCP_TRUST_PROXY`	`true` takes the client IP from `X-Forwarded-For`; it is forwarded to the API so per-IP limits apply per caller
`ETHORA_MCP_SESSION_TTL_MS`	Idle session eviction, default 4 hours
`ETHORA_MCP_AUTH_ISSUER`	Public URL of the OAuth authorization server (the Ethora API host); enables `/mcp/oauth`
`ETHORA_MCP_WIDGET_URL`	Base URL of the hosted AI chat widget (`<url>/assistant.js`) for `ethora-widget-snippet-get`
`ETHORA_MCP_PUBLIC_API_URL`	Public API base browsers can reach, emitted as `data-api-base`; falls back to `ETHORA_MCP_AUTH_ISSUER`, then a non-loopback `ETHORA_API_URL`

A .env file in the working directory is loaded at startup; real environment variables win. Credentials can also be set per session with ethora-session-configure (in memory only; on a hosted server apiUrl cannot be changed).

Endpoints (hosted)

Path	Purpose
`POST\|GET\|DELETE /mcp`	Streamable HTTP MCP endpoint, open
`POST\|GET\|DELETE /mcp/k/<api-key>`	Same, authenticated by the key in the path
`POST\|GET\|DELETE /mcp/oauth`	Same, Bearer token required, scopes enforced
`GET /healthz`	`{ ok, sessions, version, appJwtReady, oauth }`
`GET /.well-known/mcp` and `GET /`	Discovery JSON: endpoint, transport, auth options, OAuth metadata
`GET /.well-known/oauth-protected-resource[/mcp/oauth]`	RFC 9728 protected-resource metadata

Response envelope

Every tool returns JSON text in one shape: success { ok: true, ts, meta, data }, failure { ok: false, ts, meta, error } where error carries code (the API's own code when it has one), message, httpStatus, requestId and a one-line hint.

Using with stdio clients

Every stdio client runs npx -y @ethora/mcp-server; pass credentials as env vars (preferred) or call ethora-session-configure for a quick local test (its arguments end up in the transcript). For hosted mode use the one-click buttons at the top of this README, or the URL form in the quickstart. One-click buttons for the stdio package:

Cursor

json

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

VS Code (and GitHub Copilot agent mode)

.vscode/mcp.json (note the key is servers):

json

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

Claude Code

bash

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

Add --scope user to make it available in every project; verify with claude mcp list.

Claude Desktop

Settings, Developer, Edit Config (claude_desktop_config.json):

json

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

Gemini CLI, Windsurf, Cline

Same mcpServers block as above in ~/.gemini/settings.json, ~/.codeium/windsurf/mcp_config.json or cline_mcp_settings.json.

Codex CLI

~/.codex/config.toml (the table is mcp_servers with an underscore):

toml

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

Container

bash

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

Add -e ETHORA_MCP_TRANSPORT=http -e ETHORA_MCP_HTTP_HOST=0.0.0.0 -p 3030:3030 to run the hosted mode in a container.

B2B provisioning (server integrations)

With ETHORA_B2B_TOKEN configured, ethora-auth-mode-set switches the session to tenant-actor auth and ethora-b2b-app-bootstrap-ai creates an app, indexes sources (crawlUrl, docs[] as base64) and configures its bot in one call, with optional llmProvider and llmModel. ethora-b2b-app-provision adds app tokens and default rooms. ethora-user-batch-create plus ethora-user-batch-job-wait provision users asynchronously and ethora-broadcast-send plus ethora-broadcast-job-wait send a message to many rooms. ethora-b2b-runbook-generate prints the call order for your own automation.

Troubleshooting

Symptom	Meaning and fix
`TOKEN_MISSING` (401)	The session has no user token. Call `ethora-user-login` or `ethora-user-register`, or connect with a Bearer header or personal URL
`REFRESH_RECORD_NOT_FOUND` (401)	The API key or token was revoked. Create a new key
`INSUFFICIENT_SCOPE` (403) on `/mcp/oauth`	The OAuth grant lacks the scope the tool needs (`read`, `write` or `admin`). Reconnect and approve the wider scope
`This tool requires app-token auth` or `AUTH_USER_REQUIRED`	Wrong auth mode. On the hosted server stay in user mode (`ethora-auth-mode-set`); app-token mode is only for `/v2/bot` and widget routes
`AI_BOT_NOT_CONFIGURED` from the widget	No active bot on the app. Run the agent, invite and `ethora-agent-activate` steps, then reload the page
`BOT_NOT_INITIALIZED` (422) from `ethora-bot-*`	The app has no legacy per-app bot; use the agents tools instead
`AGENT_NOT_FOUND` or `APP_NOT_FOUND` (404)	Wrong id or the app was not selected; `ethora-app-select` first, or pass `appId`
`Not Acceptable` (406) from `/mcp`	The client must accept both `application/json` and `text/event-stream`
Consent page says `Social sign-in failed (auth/...)`	The Firebase code in parentheses names the cause (the browser console has the full error). `auth/popup-blocked`: allow popups for the API host. A message with no code was fixed in the backend on 2026-09-17; update if you self-host
Client cannot connect (stdio)	Run `npx -y @ethora/mcp-server` in a terminal and check Node 18 or newer
Hosted server not answering	`GET /healthz`; `appJwtReady: false` means the base app JWT bootstrap failed (check `ETHORA_APP_DOMAIN_NAME` and `ETHORA_API_URL`)

Feedback

ethora-feedback-submit sends a report (bug, unexpected, feature, docs, other) to the Ethora team from inside a session. The point of doing this over MCP rather than a web form is context: the session's last few tool failures travel with the report - tool name, error code and the API requestId - so a report can be joined to the server-side log entry instead of being re-typed from memory. Set includeRecentErrors: false when the report is unrelated to a failure.

It works whether or not the session is authenticated, because the reporter we most need to hear from is the one whose sign-up or credential is the thing that broke; an authenticated report is attributed to that account, and an anonymous one may carry an email for a reply. It is also exempt from OAuth scope enforcement, so a read-only grant can still report a problem.

Credential-shaped keys in the attached context are redacted before sending. That is key-based, so it cannot catch a credential pasted into the free-text message: the tool description tells the model not to put secrets or end-user personal data there.

Delivery is configured on the API side (FEEDBACK_EMAIL_TO, FEEDBACK_SLACK_WEBHOOK_URL, FEEDBACK_RETENTION_DAYS); the MCP server only submits.

Usage attribution

Outbound API calls carry X-Ethora-Client: mcp/<version> and, for the duration of a tool call, X-Ethora-Tool: <tool-name>. The API records these on its request log as client and source: mcp:<tool>, which is how MCP traffic is separated from the web app and counted per tool. The public unauthenticated endpoints (/ping, /apps/get-config) are left unattributed.

Security notes

Credentials are redacted from tool results. appSecret, tenantSecret, appToken, passwords and similar keys come back as [redacted] from every tool (results enter the model's context and client logs). ethora-app-credentials-reveal { appId, confirm: true } reveals an app's appToken on purpose and needs the admin scope over OAuth; the App Secret is only ever shown in the web dashboard API tab. Login, register and the api-key / app-token minting tools still return their credential once by design.
API keys and personal URLs act as the user until revoked. Keep them in your client's secret store, never in shared config or screenshots, and revoke on suspicion.
The server never logs request URLs or tokens. Keep your reverse proxy's access log free of request paths for the MCP host (the monoserver nginx template does).
Anything returned by a tool is visible to the model and stored in the conversation transcript; the server tells assistants not to print keys or passwords, and to confirm destructive tools with the user.
This repo runs report-only secret and SAST scans (gitleaks, semgrep) on pushes and PRs.

Development

Version numbers

Versions are calendar-based: YY.M.patch, where YY.M is the year and month the release ships (26.9.5 is the fifth September 2026 release, 26.10.0 the first of October) and patch counts releases within the month. No leading zero on the month, so 26.10 sorts after 26.9 under semver. Breaking changes do not bump a major; they get the next patch and a changelog entry, and earlier tool names stay callable as aliases. npm run sync-version refuses any other shape or any month other than the current one (ETHORA_VERSION_MONTH=YY.M overrides on purpose), and the publish workflow runs it. 27.0.0 and 27.1.0, published on 2026-09-24 against this rule, are deprecated; 26.9.5 is the same code.

Tool naming

Since 27.0 every listed tool follows one rule: ethora-<resource>-<verb>[-<qualifier>].

resource is a singular noun, one or two words: app, agent, chat, message, broadcast, source-site, source-doc, user, file, bot, api-key, app-token, widget, wallet, session, auth-mode, recipe, tools.
verb is the last word: create, list, get, update, delete, send, set, run, reveal, upload, crawl, reindex, start, wait, enable, disable, generate.
a qualifier only ever follows the verb: -wait (blocking form of an async job), -batch, -legacy, -b2b.
no API-version suffixes: -v2 is gone from every name. search and fetch keep their names by ChatGPT connector convention.

Every earlier name still works. Old names are aliases: never listed by tools/list, but a call to one is rewritten to the canonical tool (with a preset argument where three or two tools became one, such as ethora-auth-use-app becoming ethora-auth-mode-set { mode: "app" }), so published configs, recipes and saved conversations keep working. Results and usage attribution name the canonical tool. The full mapping is in the alias table at the end of this file and in src/toolNames.ts, which the test suite checks against the registry.

ethora-chat-component: the React chat component used in widgets and stand-alone apps
ethora-monoserver: deploy automation that ships this server as an optional service (private repository, available to enterprise customers)
ethora-wp-plugin: WordPress integration
rag_demos: RAG AI assistant examples

Quality and maintenance score

Independently inspected by Glama, which builds the server, catalogues its tools and rates tool-definition quality and maintenance activity.

Earlier tool names

Names used before 27.0 and the tool each one now resolves to. All of them remain callable.

Earlier name	Canonical tool
`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` with `{"mode": "app"}`
`ethora-auth-use-b2b`	`ethora-auth-mode-set` with `{"mode": "b2b"}`
`ethora-auth-use-user`	`ethora-auth-mode-set` with `{"mode": "user"}`
`ethora.b2b.auth.use`	`ethora-auth-mode-set` with `{"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`

License

See LICENSE.

Install

Tools (91)

ethora-configureethora-statusethora-helpethora-run-recipeethora-doctorethora-auth-use-appethora-auth-use-userethora-auth-use-b2b

Configuration

Environment variables

ETHORA_API_URL

Full Ethora API URL. Defaults to https://api.chat.ethora.com/v1 if neither ETHORA_API_URL nor ETHORA_BASE_URL is set.

ETHORA_BASE_URL

Base host URL (e.g. https://api.chat.ethora.com). The server appends /v1 automatically. Use ETHORA_API_URL instead if you need a non-/v1 path.

ETHORA_APP_JWTsecret

App JWT used for the user-auth bootstrap flow (login/register). Usually starts with 'JWT '. Optional; can also be set at runtime via the ethora-configure tool.

ETHORA_B2B_TOKENsecret

B2B server token used for tenant-actor x-custom-token auth (JWT with type=server). Required for B2B / app provisioning flows. Optional; can also be set at runtime.

ETHORA_MCP_ENABLE_DANGEROUS_TOOLS

Set to 'true' to expose destructive tools (app deletion, wallet transfers, bulk delete). Disabled by default.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "ethora-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@ethora/mcp-server@26.9.5"
      ],
      "env": {
        "ETHORA_API_URL": "<YOUR_ETHORA_API_URL>",
        "ETHORA_BASE_URL": "<YOUR_ETHORA_BASE_URL>",
        "ETHORA_APP_JWT": "<YOUR_ETHORA_APP_JWT>",
        "ETHORA_B2B_TOKEN": "<YOUR_ETHORA_B2B_TOKEN>",
        "ETHORA_MCP_ENABLE_DANGEROUS_TOOLS": "<YOUR_ETHORA_MCP_ENABLE_DANGEROUS_TOOLS>"
      }
    }
  }
}