ethora-mcp-server

Create Agent

ethora-agent-create

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 them into the same room. See the ethora-agents-quickstart prompt for the end-to-end recipe. To start from a ready-made public agent instead, ethora-agent-list { visibility: "public" } then ethora-agent-clone. Requires: a selected app (ethora-app-select) or an explicit appId. The agent belongs to your account (only you can change it) and is homed in that app; it can still be used in your other apps.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	No	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`	No	URL-safe slug (auto-generated from name if omitted).
`appId`	No	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.
`isRAG`	No	Enable retrieval-augmented generation from indexed sources.
`prompt`	No	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.
`ragTags`	No	Optional RAG tag filter — restrict retrieval to sources matching these tags.
`summary`	No	Short bio shown in agent lists.
`trigger`	No	Legacy trigger field. Prefer the newer `responseMode` for new agents.
`llmModel`	No	Model id served by this deployment's AI endpoint; omit for the platform default. `ethora-agent-model-list` returns the supported ids; an unsupported id is rejected with LLM_MODEL_UNSUPPORTED and that list.
`flowsYaml`	No	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.
`categories`	No	Directory categories, any of: `customer-support` (customer-facing assistants), `persona` (a character or historical figure), `entertainment` (quizzes, games, scenarios), `worker` (internal work). Used to filter `ethora-agent-list`. Replaces the agent's current set.
`visibility`	No	'private' (only invitable inside the owning app) or 'public' (cross-app invitable).
`cooldownSec`	No	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.
`isPublished`	No	Convenience alias for setting visibility='public'.
`llmProvider`	No	Leave empty. The deployment has one AI endpoint (OpenAI-compatible); `openai` and `openai-compatible` are accepted as synonyms, anything else is rejected with LLM_PROVIDER_UNSUPPORTED.
`botAvatarUrl`	No	URL of the avatar image shown next to bot messages.
`responseMode`	No	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`.
`botDisplayName`	No	Display name used inside the chat UI. Defaults to `name`.
`greetingMessage`	No	Optional message the agent posts when it first joins a room.
`responseProbability`	No	If responseMode='probability', odds (0-1) of replying to each message. Damped 0.6x for bot-to-bot messages.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 16, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true) by disclosing auth-mode constraints — app-token mode is rejected by the backend — plus ownership/homing semantics ('belongs to your account', 'homed in that app'). It does not cover duplicate-name/slug behavior or the shape of the created resource, which matters for a non-idempotent create.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool does and the endpoint, then moves to auth modes, then to alternatives and prerequisites. Every sentence carries information, though the final 'Requires:' paragraph could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter, zero-required-parameter create tool with no output schema, the description supplies prerequisites, auth modes, ownership, and the multi-agent recipe. The one gap is that it never says what the call returns (e.g. the new agent's id), which the caller needs before inviting or updating it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already documents all 20 fields in detail, so the baseline is 3. The description adds useful framing by grouping the fields into 'persona' vs 'response-gate settings' and calling out `responseMode`/`cooldownSec` interplay, but no syntax or format beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a reusable AI agent') and even names the backing endpoint. It distinguishes itself cleanly from siblings by contrasting with `ethora-agent-update`, `ethora-agent-clone`, and `ethora-agent-invite` in the same paragraph.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: use this for one persona, repeat for multi-agent scenarios, then `ethora-agent-invite`; or start from a public template via `ethora-agent-list { visibility: "public" }` + `ethora-agent-clone`; and points at the `ethora-agents-quickstart` prompt. Prerequisite is stated ('a selected app ... or an explicit appId').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ethora-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Create Agent

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources