MCP

The Elaras Ask MCP server exposes your agent workspace as Model Context Protocol tools so any MCP client — Claude Desktop, Claude Code, Cursor, Zed — can build, version, test, and manage agents programmatically.

Public endpoint: https://ask-api.elaras.ai/mcp (Streamable HTTP transport)

What it's for

Automate agent construction — script agent creation, knowledge ingestion, personality versioning, skill/flow wiring
Test conversations in a loop — send preview messages, read the full trace (which skills fired, with what inputs and outputs, flow transitions, token counts), and iterate
Regression-test with scenarios — declarative multi-turn test cases with an AI judge for required_facts; run one or all, get pass/fail per turn

Install

Two auth modes. Pick one per client.

Option A — OAuth via browser (recommended for interactive clients)

Best for Claude Desktop, Cursor, Zed. No API key to paste anywhere.

Claude Desktop: Settings → Connectors → Add custom connector

Name: Elaras Ask
URL:  https://ask-api.elaras.ai/mcp

Click Connect. A browser opens ElarasAuth → sign in → consent to chat:read chat:write → tokens are stored by Claude Desktop. Tools appear in the tool picker.

Claude Code CLI:

claude mcp add --transport http elaras-chat https://ask-api.elaras.ai/mcp

First tool invocation triggers the OAuth browser flow. Subsequent calls reuse the stored token.

Cursor / Zed: same as Claude Desktop pattern — check each client's MCP config docs. All follow the RFC 9728 protected-resource discovery pointer we emit on 401.

Option B — Personal Access Token (recommended for CI + automation)

Best when you want a long-lived key without a browser, e.g. GitHub Actions.

1. Sign in to your Elaras dashboard.
2. Go to Developer → New Key.
3. Give it a name (e.g. ci-github-actions) and click Create Key.
4. Copy the sk_... value — shown once.
5. Add to your MCP client's config file:

{
  "mcpServers": {
    "elaras-chat": {
      "transport": "http",
      "url":       "https://ask-api.elaras.ai/mcp",
      "headers":   { "Authorization": "Bearer sk_..." }
    }
  }
}

Rotate anytime from Developer → API Keys. Old key is invalidated instantly.

Tool catalog

54 tools across 7 domains. Every call is scoped to the team owning the bearer token.

Agents (5)

Tool	Purpose
`list_chatbots`	List every agent in your workspace
`get_chatbot`	Fetch one agent's config
`create_chatbot`	Create a new agent
`update_chatbot`	Change name, description, status, or assigned personality
`delete_chatbot`	Permanently remove an agent (destructive; ask before running)

Personalities + Versions (12)

Personalities are reusable AI configurations (system prompt, greeting, Anthropic model choice). Agents reference a published personality version — never a draft. See Personality.

Tool	Purpose
`list_models`	All models in workspace
`get_model`	One model + its versions
`create_model`	New model — accepts optional inline `system_prompt`, `greeting`, `underlying_model`
`update_model`	Rename or change model settings
`delete_model`	Remove a model and all its versions
`list_model_versions`	Versions of one model (draft + published)
`create_model_version`	New draft version of a model
`update_model_version`	Edit a draft (published versions are immutable)
`publish_model_version`	Freeze a draft as published; gated on ≥1 passing scenario
`clone_model_version`	Copy a version as a new draft (fork for experimentation)
`delete_model_version`	Remove a version
`assign_model_to_chatbot`	Point an agent at a specific published personality version

Scenarios + Scenario Runs (17)

Multi-turn test cases with pass/fail per turn. AI judge scores required_facts in each expected assistant reply. See Scenarios.

Tool	Purpose
`list_model_scenarios`	Scenarios owned by a model
`add_model_scenario`	New scenario against a model
`update_model_scenario`	Edit an existing scenario
`delete_model_scenario`	Remove a scenario
`draft_model_scenarios`	AI-drafts candidate scenarios from your model's system prompt
`list_chatbot_scenarios`	Scenarios owned by an agent (rarer; usually personality-scoped)
`add_chatbot_scenario`	New scenario against an agent
`start_model_scenario_run`	Kick off a run against a model version
`get_model_scenario_run`	Fetch results for a run
`list_model_scenario_runs`	All runs for a model
`cancel_model_scenario_run`	Stop a running run
`compare_model_scenario_runs`	Side-by-side diff between two runs (e.g. before/after a prompt change)
`start_chatbot_scenario_run`	Same for agent-scoped scenarios
`get_chatbot_scenario_run`	"
`list_chatbot_scenario_runs`	"
`cancel_chatbot_scenario_run`	"
`wait_for_scenario_run`	Blocking helper — poll until a run completes, then return results

Skills (5)

Skills let the AI call your HTTP endpoints during a conversation. See Skills.

Tool	Purpose
`list_skills`	All skills in workspace
`create_skill`	Register a new skill (name, description, endpoint URL, input_schema, output_schema)
`update_skill`	Edit skill config
`delete_skill`	Remove a skill
`test_skill`	Fire a test invocation with arbitrary inputs and inspect the response

Flows (5)

Deterministic conversation flows — set of states with transitions triggered by user intent or a skill result.

Tool	Purpose
`list_flows`	All flows in workspace
`create_flow_via_ai`	Describe a flow in natural language; AI generates the flow spec
`update_flow`	Edit an existing flow
`delete_flow`	Remove a flow
`attach_flow_to_chatbot`	Link a flow to an agent

Preview (2)

Send test messages against any agent and get the full trace back.

Tool	Purpose
`send_preview_message`	Send one message; response includes the assistant text + full trace
`clear_preview_session`	Reset a preview session's history

Knowledge (8)

Documents your agent can retrieve for RAG. Chunk text is never exposed via MCP — only document metadata.

Tool	Purpose
`list_knowledge`	All documents in workspace
`get_knowledge`	One document's metadata + indexing status
`add_knowledge_url`	Fetch a URL, extract text, embed, index
`add_knowledge_crawl`	Crawl a website, add every page as a document
`add_knowledge_qa`	Add a Q&A pair (fastest path — no scraping)
`wait_for_knowledge_indexing`	Blocking poll until a document is `indexed` or `failed`
`delete_knowledge`	Remove a document (permanent)
`resync_knowledge`	Refetch + re-embed an existing URL-sourced document

Preview response

send_preview_message returns a full trace alongside the assistant's reply so you can see exactly what happened during the turn:

{
  "session_token": "01HXYZ...",
  "response":      "It is 12:00 UTC.",
  "credits_used":  2,
  "enrichment":    null,
  "trace": {
    "skills_called": [
      {
        "name":       "get_time",
        "input":      { "tz": "UTC" },
        "output":     "{\"time\":\"12:00\"}",
        "latency_ms": 42
      }
    ],
    "flow_transitions": [
      { "from": "greeting", "to": "asking_purpose", "trigger": "user_provided_name" }
    ],
    "model_used":     "claude-sonnet-4-6",
    "input_tokens":   150,
    "output_tokens":  30
  }
}

Fields:

skills_called — every skill invoked this turn, with the AI-generated input, your endpoint's output (truncated to 4KB), and wall-clock latency. Assert that the agent called the right skill with the right args.
flow_transitions — flow state changes triggered by this turn.
model_used — the underlying Anthropic model that answered.
input_tokens / output_tokens — for cost accounting.

Example workflows

Build an agent from scratch, publish, verify

Prompt Claude Desktop / Code:

Build an agent for a small vet clinic:

Add knowledge for hours (Mon-Fri 8am-6pm, Sat 9am-1pm), phone (555-0123), and services (routine checkups, vaccinations, emergencies).

Create a personality with a friendly, concise tone.

Add three scenarios covering hours, phone number, and emergency handling.

Run the scenarios; publish the personality version once they pass.

Assign the published version to the agent.

Send a preview message "when are you open on saturday?" and confirm 9am to 1pm appears.

Iterate a scenario until it passes

Test scenario scn_abc123 against model version mv_xyz789. If any turn fails, tell me which required_facts were missing and suggest a system-prompt tweak that would fix it. Loop until it passes.

Regression-test after a prompt change

Clone the currently-published version of personality Concierge as a new draft. Update the greeting to say "Welcome to the Blue Room." Run every existing scenario against the draft. Compare pass rates between the draft run and the last published run. If the draft doesn't regress, publish it and reassign the agent.

Tool safety annotations

Every write tool carries MCP tool annotations so client UIs can decide whether to auto-run or ask for confirmation:

Annotation	Meaning	Example tools
`readOnlyHint: true`	Never mutates state. Safe to auto-run.	`list_`, `get_`, `wait_for_`, `compare_`, `test_skill`, `send_preview_message`
`destructiveHint: true`	Removes data or does something hard to reverse. Clients should confirm.	`delete_*`, `publish_model_version` (irreversibly freezes a version)
`idempotentHint: true`	Calling twice with the same args has the same effect as once. Safe to retry.	`update_*`, `assign_model_to_chatbot`, `attach_flow_to_chatbot`, `resync_knowledge`

Claude Desktop, Cursor and Claude Code all honour these — you'll see a confirmation prompt before any destructiveHint tool runs. test_skill and send_preview_message are marked read-only despite hitting your endpoints, because they don't mutate Elaras state.

Scope enforcement

sk_ PATs and OAuth tokens carry scopes. Requests without the right scope return 403 insufficient_scope.

Scope	Grants
`read` (or `chat:read`)	`list_`, `get_`, `wait_for_`, `compare_`
`write` (or `chat:write`)	Everything else (`create_`, `update_`, `delete_`, `publish_`, `add_`, `test_`, `send_preview_message`, `start_*_run`, etc.)

For OAuth clients the scopes are namespaced (chat:read, chat:write) so consent screens can group them by product. Both forms are accepted.

Rate limits

60 requests/minute per team. Applies across sk_ PAT and OAuth tokens for the same team.

Bulk workflows (e.g. seeding 50 scenarios) should space calls with a short delay or split across multiple keys.

Support

Email [email protected] for any issue — bug reports, integration questions, or urgent production incidents. Please include the MCP tool name, the arguments you called it with, and the response you received.