@three-ws/concierge-mcp (MCP Server)

The MCP server “io.github.nirholas/concierge-mcp” provides a workflow to ask an AI concierge on any website a grounded question, then generate an embed for adding that concierge to a site. It targets developers integrating AI concierge experiences via MCP tooling.

🛠️ Key Features

Ask a website’s AI concierge grounded questions
Generate an embed to add the concierge to a site
Topics include mcp, oauth, llm, javascript, typescript, and web components/webgl-related tooling

🚀 Use Cases

Integrate an AI concierge widget/embed into a website
Use any AI assistant to answer questions via a website concierge
Add concierge functionality for web experiences using web-component approaches

⚡ Developer Benefits

MCP-oriented integration (tooling via “mcp”)
OAuth is listed as a topic, indicating auth-related concerns
JavaScript/TypeScript compatibility is indicated by topics

⚠️ Limitations

The provided description focuses on concierge Q&A and embed generation; no additional capabilities, tool count, or runtime constraints are included in the available source data.

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

license node

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

bash

npm install @three-ws/concierge-mcp

Or run with npx (no install):

bash

npx @three-ws/concierge-mcp

Quick start

Claude Code, one line:

bash

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

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

json

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

Inspect the surface with the MCP Inspector:

bash

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

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

bash

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.