three.ws Concierge

@three-ws/concierge-mcp

Ask any website's AI concierge a grounded question, and generate the embed to add one to a site, from any AI assistant.

A Model Context Protocol server that puts the three.ws Concierge, the embeddable AI chat widget with a talking 3D avatar, in reach of any AI assistant over stdio.

Three tools:

No API key, no signer, no payment. concierge_ask runs on the public, free POST /api/concierge answer lane; the other two are pure local generators.

Install

npm install @three-ws/concierge-mcp

Or run with npx (no install):

npx @three-ws/concierge-mcp

Quick start

Claude Code, one line:

claude mcp add concierge -- npx -y @three-ws/concierge-mcp

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

{

"mcpServers": { "concierge": { "command": "npx", "args": ["-y", "@three-ws/concierge-mcp"] } } }

Inspect the surface with the MCP Inspector:

npx -y @modelcontextprotocol/inspector npx -y @three-ws/concierge-mcp

What you can do with it

Ask any website a question, grounded in its real content:

Use concierge_ask to answer "what does the Pro plan include?" from https://example.com/pricing

The server fetches the page, harvests its readable text, sends it to the concierge answer engine, and returns an answer that is told not to invent anything the page doesn't say.

Ask from text you already have (no URL):

concierge_ask: question = "what's the refund window?", knowledge = "Returns accepted within 30 days."

Generate a copy-paste embed for a site:

Use concierge_embed for siteName "Acme", accent "#f97316", avatar "nova", suggestions ["What is Acme?", "Pricing?"], flavor "script"

Returns the exact tag to drop into the site's HTML.

Pick an avatar first:

concierge_avatars → then use the id you like as concierge_embed's avatar

Tools in detail

concierge_ask

Read-only, open-world.

At least one of url, knowledge, or content is required. Returns { ok, question, answer, grounded_in, provider, model, endpoint }.

concierge_embed

Read-only, idempotent, offline.

Key parameters: siteName, flavor (script \| web-component \| npm \| imperative \| all, default all), accent, avatar, customAvatar, position, theme, greeting, persona, knowledge, suggestions[], endpoint, muted, open, noPicker, noTeaser, lang. Returns { ok, flavor, snippets, applied_config, docs }. The script, web-component, and imperative snippets are all plain-HTML paste-ready (they load the CDN global build); the npm snippet is for bundler users.

concierge_avatars

Read-only, idempotent, offline. No parameters. Returns { ok, default, count, avatars, note }, each avatar carrying id, name, tagline, style, and framing.

Configuration

All optional environment variables:

Errors

A failed tool call returns an MCP error result (isError: true) whose text is a single JSON object: { "ok": false, "error": " ", "message": "…" }, plus status on upstream rejections:

How it relates to the widget

This server is the agent-facing side of @three-ws/concierge, the browser widget. Same answer engine, same avatar catalog, same grounding model, exposed as MCP tools so an assistant can *use* a site's concierge or *install* one, not just a human visitor.

• Widget + docs: three.ws/concierge
• Reference docs: three.ws/docs/concierge
• Build tutorial: three.ws/docs/tutorials/build-a-site-concierge

Develop

npm test    # node --test, offline (registration, harvest, embed, SSE parsing)

npm start # run the server over stdio

A live end-to-end check against a running three.ws (test/_manual-e2e.mjs) drives all three tools through a real stdio client; see the file header to run it.

License

Apache-2.0. See LICENSE. Free to run against the public three.ws API.