Skip to Content
User GuideChocolate Factory Integration

Chocolate Factory Integration

Chocolate Factory  lets you add an AI chat assistant to your published website, so visitors get answers from an AI agent.

This is different from connecting an AI tool, which lets your team work on the site through AI. Chocolate Factory is for your website’s visitors.

How it works

This is a manual integration. Visor doesn’t create anything in Chocolate Factory for you, or the other way round. You move between the two and copy the details across yourself.

What you copyCopy it fromPaste it into
The site’s MCP address and a personal tokenVisor: Settings → AI toolsChocolate Factory: the MCP server
The Chocolate Factory addressChocolate Factory: the agent’s Integrations tabVisor: Chocolate Factory Domain
An Agent API keyChocolate Factory: the agent’s Integrations tabVisor: Project API Key
The Agent IDChocolate Factory: the agent’s Integrations tabVisor: Agents

What you need

  • A Chocolate Factory account, assigned to your site’s project.
  • A role at the site that can save its frontend’s settings, usually Site Admin.

Set it up

In Chocolate Factory: sign in

Sign in to your Chocolate Factory. If you have forgotten your password, use Sign in with Magic Link. See Sign in to your account .

Sign in with a magic link

Choose your project from the project menu at the top of the page.

Choosing a project, and Database & Tools in the sidebar

In Visor: get the connection details

The agent reads your site through the Visor MCP. Go to Settings → AI tools and create a personal token:

  • Under what it may do, tick only See the site’s pages, content, content types and files.
  • Under Expires after, choose how long it should last.

Copy the token, because it is shown once. Copy the site’s MCP address from Connect your AI tool as well:

https://<your-visor-address>/api/mcp/sites/<organization-id>/<site-id>

In Chocolate Factory: add the MCP server

Click Database & Tools in the sidebar. On the MCP Servers tab, click Add MCP Server or Create, and choose Custom.

Adding an MCP server

Fill in the form:

FieldValue
Server NameSomething you’ll recognise, such as the site’s name.
Server URLThe site’s MCP address from Visor.
AuthenticationCustom, with the header below.
{ "Authorization": "Bearer <your personal token>" }

Click Create. Chocolate Factory checks the connection and loads the server’s tools. If the server’s status isn’t healthy, check the address and the token.

In Chocolate Factory: create the agent

Click Agents in the sidebar, then Create Agent. Fill in its name, role, description and model, then use its Configuration tab to set how it should behave.

In Chocolate Factory: give the agent the MCP server

On the agent’s Tools tab, under MCP Servers, click Add MCP Server and choose your server. Expand Available Tools, turn on only the tools it needs to read your site, and save.

The agent's Tools tab

In Chocolate Factory: activate and test it

Turn on the Active switch beside the agent’s picture and save. Open Dashboard, choose the agent, and ask it something about your site.

In Chocolate Factory: copy the agent’s details

Open the agent’s Integrations tab.

The agent's Integrations tab

Copy these three things:

CopyWhereExample
Agent IDAt the top of the tab.00000000-0000-0000-0000-000000000000
The Chocolate Factory addressThe start of Run API URL, up to but not including /api.https://your-chocolate-factory.example.com
An Agent API keyUnder Agent API Keys, enter a Key Name and click Add Key. It is shown once.agk_...

Use an Agent API key, never an organization key. The chat runs in visitors’ browsers, so they can see this key. An Agent API key only reaches this one agent. An organization key reaches every agent in your organization.

In Visor: connect the frontend

Go to Settings → Frontend and click Manage on your frontend. On the Settings tab, open Site Configuration and find Chocolate Factory Integration.

The Chocolate Factory Integration setting

Turn on the switch, then fill in the card:

FieldPaste
Chocolate Factory DomainThe Chocolate Factory address. An Open Dashboard button then appears.
Project API KeyThe Agent API key. If an older site already has a key here, leave it.
AgentsClick Add Agent, paste the Agent ID, enter an Agent Name, and click Add.

Click Save at the top of the page.

In Visor: add the chat to a page

Edit a page and drag Chocolate Factory Chat from the Widgets panel, in the Interactive category. In its settings, choose:

SettingValue
Frontend SiteYour frontend. This fills in the Chocolate Factory address and key.
AgentThe agent you added.
Chat Title, Welcome Message, Primary Color, Widget Position, Avatar URLHow the chat looks.

If the widget isn’t in the panel, the site may be hiding the template’s widgets. See Layouts.

In Visor: publish and deploy

Publish the page, then Deploy. In Edit mode the widget only shows a summary of its settings. The real chat appears on the published page.

Keep it working

IfThen
The personal token is about to expireIn Visor, create a new one. In Chocolate Factory, replace it on the MCP server.
The token’s owner leaves the siteDo the same, as someone who still works at the site.
The personal token has leakedDisconnect it straight away, then create a new one.
The Agent API key is compromisedIn Chocolate Factory, replace it on the agent’s Integrations tab. In Visor, paste the new one into Project API Key, save, and open the chat widget’s settings to choose Frontend Site again. Then publish the page and Deploy.
You want a different agentCreate the agent and its key, and repeat the Visor steps. A frontend holds one key, and an Agent API key reaches one agent, so a frontend serves one agent at a time.
You want to remove the chatTurn off the switch, save and Deploy. The widget then shows nothing.

The agent can read whatever the token’s owner can read at the site, which may include unpublished content. Visitors could get answers based on it. Create the token as someone whose access suits this, and test the agent before you publish the chat.

For developers

Chocolate Factory Chat is a sample widget in the site template. A developer or AI tool can adapt it with the template’s chocolate-factory-sdk skill. See Skills.

The widget reads its settings from the frontend’s configuration and shows nothing if the integration is turned off.

Last updated on