diff --git a/src/_data/sidebars/help.yml b/src/_data/sidebars/help.yml index 425751ae..482f3b82 100644 --- a/src/_data/sidebars/help.yml +++ b/src/_data/sidebars/help.yml @@ -161,6 +161,8 @@ resources: link: /mcp-servers/deploy-workflows/ - label: Use an MCP server link: /mcp-servers/use-mcp-server/ + - label: Agent chat widget and headless client + link: /mcp-servers/agent-chat-widget-headless-client/ - label: Access management link: /mcp-servers/access-management/ - label: Secrets and config @@ -172,10 +174,10 @@ resources: - label: Security link: /mcp-servers/security/ - type: category - label: Customization options - items: - - label: Custom domains - link: /mcp-servers/customization-options/custom-domain/ + label: Customization options + items: + - label: Custom domains + link: /mcp-servers/customization-options/custom-domain/ - label: Specification support items: - label: Flower support diff --git a/src/_help/mcp-servers/agent-chat-widget-headless-client.md b/src/_help/mcp-servers/agent-chat-widget-headless-client.md new file mode 100644 index 00000000..3a5fd33d --- /dev/null +++ b/src/_help/mcp-servers/agent-chat-widget-headless-client.md @@ -0,0 +1,127 @@ +--- +title: Agent chat widget and headless client +--- + +- TOC +{:toc} + +Every MCP server can also be reached as a conversational agent: no MCP client or AI tool required on the other end. Turn on **Agent** in your MCP server settings to get an agent endpoint, ready to plug into an embeddable Bump.sh chat widget or your own interface. + +![Agent toggle and endpoint in MCP server settings](/docs/images/help/mcp-servers/mcp-servers-agent-activation.png) + +The agent endpoint follows the format `https://run.bump.sh/ORGANIZATION_SLUG/MCP_SERVER_SLUG/agent`, or your `https://your-custom-domain.com/agent` if you [set one up](/help/mcp-servers/customization-options/custom-domain/). + +From there, you have two ways to build on it, both from the open-source [`agent-client`](https://github.com/bump-sh/agent-client) SDK: + +| | What it does | Use it when | +|---|---|---| +| [**Chat widget**](#chat-widget) | A ready-to-use, embeddable chat UI (Web Component). | You want to add a working chat widget to your app in a few lines of code. | +| [**Headless client**](#headless-client) | A dependency-free client that streams the conversation, with no interface. | You're building your own UI: a Slack bot, a CLI, a custom chat panel, ... | + +## Chat widget + +A ready-to-use chat widget for your product, so your own users can run your workflows straight from your app in natural language: no external LLM tool or MCP client needed on their end. It's a Web Component that can easily be added to your page in HTML or JavaScript. + +![The chat widget open on a demo page, in modal mode](/docs/images/help/mcp-servers/mcp-servers-chatbot-demo.gif) + +### Try it in the playground + +Before writing any code, test and customize the chat widget against your real endpoint in the [playground](https://bump-sh.github.io/agent-client/). + +> You can find a playground link pre-filled with the agent endpoint in your MCP server settings. +{: .info} + +Every option you tweak (mode, theme, title, greeting, ...) is reflected live in the preview. The code panel gives you the JS or HTML snippet to copy into your app to get your customized chat widget live. + +![Agent playground showing a live widget preview next to the generated code snippet](/docs/images/help/mcp-servers/mcp-servers-chatbot-playground.png) + +### Install and embed + +[`@bump-sh/agent-widget`](https://github.com/bump-sh/agent-client/tree/main/packages/agent-widget) provides a chat panel and an access button in a few lines of code. It has no dependencies and stays isolated from your page's styles (Shadow DOM). + +```sh +npm install @bump-sh/agent-widget +``` + +```ts +import { Widget } from "@bump-sh/agent-widget" + +new Widget({ endpoint: "https://run.bump.sh/ORGANIZATION_SLUG/MCP_SERVER_SLUG/agent" }) +``` + +Or declaratively, straight from a CDN, with no build step: + +```html + + +``` + +### Display modes + +| Mode | Behavior | +|------|----------| +| `modal` (default) | Access button that opens a centered chat window. | +| `sidebar` | Access button that opens a chat panel docked to the side. | +| `inline` | Always-open chat, mounted directly into an element on your page (`target`). | + +Here, `mode` switches to the always-open layout `inline`, and `target` gives the CSS selector of the element to add it into. + +```ts +new Widget({ endpoint, mode: "inline", target: "#chat" }) +``` + +### Customization + +Most of the widget's UI is customizable through options passed to `new Widget({ ... })`. Here's a list of the most commonly used: + +| Option | Description | +|--------|-------------| +| `title`, `greeting`, `suggestions` | Header text, optional opening message, clickable example prompts. | +| `theme` | Common CSS tokens (`accent`, `bg`, `text`, `font`, `radius`, ...). | + +> See the [widget README](https://github.com/bump-sh/agent-client/tree/main/packages/agent-widget#options) for the complete list of options. +{: .info} + +## Headless client + +If you'd rather build your own UI, use [`@bump-sh/agent-conversation`](https://github.com/bump-sh/agent-client/tree/main/packages/agent-conversation) directly: it's the same streaming client the widget is built on, with no interface attached. + +```sh +npm install @bump-sh/agent-conversation +``` + +```ts +import { Conversation } from "@bump-sh/agent-conversation" + +const conversation = new Conversation({ endpoint: "https://…/agent" }) + +// await the full reply… +const reply = await conversation.send("What's the weather in Paris?") + +// …or stream every event +for await (const event of conversation.send("And in Lyon?")) { + if (event.type === "text") append(event.delta) +} +``` + +Events, error handling, cancellation, and the wire protocol are covered in the [conversation README](https://github.com/bump-sh/agent-client/tree/main/packages/agent-conversation#error-handling). + +## Authentication and per-user data + +Your workflow might need something specific to the current user: a personal API key, a workspace ID, ... You can pass it in from the client. Each can be a static value or a function called again on every request, handy for a token that expires: + +- `token`: sent as `Authorization: Bearer `, available in your workflow as `$current_user.token`. You should use a short-lived, user-scoped token. +- `config`: sent as `Config-` headers, available as `$config.` runtime expression in your workflow definition. A `headers` option covers any other custom header. + +```ts +new Widget({ + endpoint, + token: async () => (await fetch("/agent-token")).text(), + config: { locale: "fr" }, +}) +``` + +The same options work on the headless client: `new Conversation({ endpoint, token, config })`. + +> See [Secrets and config](/help/mcp-servers/secrets-and-config/) for how these values are used inside a workflow. +{: .info} \ No newline at end of file diff --git a/src/_help/mcp-servers/index.md b/src/_help/mcp-servers/index.md index ae72618a..af169064 100644 --- a/src/_help/mcp-servers/index.md +++ b/src/_help/mcp-servers/index.md @@ -34,7 +34,7 @@ Both formats support multi-step sequences, conditional logic (retry, goto, end), 1. [Create an MCP server](/help/mcp-servers/create-and-manage-mcp-servers/) from your dashboard. 2. [Deploy a workflow document](/help/mcp-servers/deploy-workflows/) that describes the API calls your server can perform. -3. Share the server URL so that end-users can [add it to their AI tool](/help/mcp-servers/use-mcp-server/). +3. Share the server URL so that end-users can [add it to their AI tool](/help/mcp-servers/use-mcp-server/), or [embed a chat widget](/help/mcp-servers/agent-chat-widget-headless-client/) directly in your product. ## Go further diff --git a/src/_help/mcp-servers/use-mcp-server.md b/src/_help/mcp-servers/use-mcp-server.md index 4802014c..15bc26da 100644 --- a/src/_help/mcp-servers/use-mcp-server.md +++ b/src/_help/mcp-servers/use-mcp-server.md @@ -10,6 +10,12 @@ To use an MCP server, the most common way is to add it to your IDE or AI tool. S >If your Bump.sh MCP server is private, don't forget to select OAuth as the authentication type while adding the server to your tool. {: .info} +## Embed a chat widget in your own product + +Rather than asking users to add your MCP server to a third-party tool, you can enable the **Agent** endpoint in your MCP server settings and embed a ready-made chat widget directly in your product. See [Agent chat widget and headless client](/help/mcp-servers/agent-chat-widget-headless-client/). + +![The chat widget open on a demo page, in modal mode](/docs/images/help/mcp-servers/mcp-servers-chatbot-demo.gif) + ## ChatGPT To add an MCP server to ChatGPT, go to Settings -> Apps -> Advanced settings -> Create app, and fill the MCP server URL field. diff --git a/src/docs/images/help/mcp-servers/mcp-servers-agent-activation.png b/src/docs/images/help/mcp-servers/mcp-servers-agent-activation.png new file mode 100644 index 00000000..55e9aeee Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-agent-activation.png differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-chatbot-demo.gif b/src/docs/images/help/mcp-servers/mcp-servers-chatbot-demo.gif new file mode 100644 index 00000000..f4193414 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-chatbot-demo.gif differ diff --git a/src/docs/images/help/mcp-servers/mcp-servers-chatbot-playground.png b/src/docs/images/help/mcp-servers/mcp-servers-chatbot-playground.png new file mode 100644 index 00000000..90413716 Binary files /dev/null and b/src/docs/images/help/mcp-servers/mcp-servers-chatbot-playground.png differ