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:

| Tool | What it does | Network | | --- | --- | --- | | concierge_ask | Ask a website's AI concierge a question. Give it a url and it fetches that page and answers grounded in the real content (title, headings, nav, main text), the way to ask any website a question. Or pass knowledge/content to answer from text you already have. | Free three.ws lane + fetches the URL | | concierge_embed | Generate ready-to-paste embed code that adds a Concierge to a website: the one-tag <script>, the <three-concierge> web component, or an npm snippet, configured with accent, avatar, greeting, curated knowledge, and suggested prompts. | Offline | | concierge_avatars | List the rigged 3D avatars a Concierge can wear. | Offline |

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

| Parameter | Type | Notes | | --- | --- | --- | | question | string (required) | The question, in natural language. | | url | string (url) | A page to ground the answer in. Fetched + harvested. | | siteName | string | Display name; inferred from the page when omitted. | | knowledge | string | Curated authoritative facts. Leads over harvested text. | | content | string | Raw text to ground in when you pass no url. | | persona | string | Tone instruction for the reply. | | lang | string | BCP-47 hint, e.g. en, es. |

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

concierge_embed

Read-only, idempotent, offline.

Key parameters: siteName, flavor (script | web-component | npm | imperative | all), accent, avatar, customAvatar, position, theme, greeting, persona, knowledge, suggestions[], endpoint, muted, open, noPicker, noTeaser, lang. Returns { snippets, applied_config }.

concierge_avatars

Read-only, idempotent, offline. No parameters. Returns the catalog (id, name, tagline, style).

Configuration

All optional environment variables:

| Variable | Default | Purpose | | --- | --- | --- | | THREE_WS_BASE | https://three.ws | API origin for the answer call + the origin the embed snippets point at. | | THREE_WS_TIMEOUT_MS | 45000 | Timeout for the concierge answer (it may fail over across LLM providers). | | CONCIERGE_PAGE_TIMEOUT_MS | 12000 | Timeout for fetching a page in concierge_ask. |

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

Proprietary. See LICENSE. Free to run against the public three.ws API.