Skip to main content

AI Integration FAQ

This FAQ covers Unchained Engine's AI capabilities. It is written for both human developers and AI agents consuming this documentation.

General​

What AI features does Unchained Engine provide?​

Three integration surfaces:

  1. MCP Server — A Model Context Protocol server at /mcp that exposes the full commerce API as AI-callable tools. Compatible with Claude Desktop, Claude Code, Cursor, and any MCP client.
  2. Admin Copilot — A chat interface in the Admin UI powered by the Vercel AI SDK. Connects to the MCP server internally.
  3. llms.txt — Static files (docs.unchained.shop/llms.txt and /llms-full.txt) published by this documentation site (not the engine) that help LLMs discover and navigate the documentation.

Which AI models are supported?​

  • Admin Copilot: Any model supported by the Vercel AI SDK — OpenAI, Anthropic, Google, Mistral, local models via OpenAI-compatible APIs, and more.
  • MCP Server: Model-agnostic. Any MCP-compatible client can connect regardless of the underlying model.

Can I use a local/self-hosted LLM?​

Yes. Any service that exposes an OpenAI-compatible API endpoint works with the Admin Copilot. See the self-hosted LLM setup.

MCP Server​

What is the MCP endpoint URL?​

/mcp on your engine's root URL. For example, if your engine runs at https://engine.example.com, the MCP endpoint is https://engine.example.com/mcp. The path is configurable via the MCP_API_PATH environment variable.

What authentication does the MCP server require?​

An authenticated user with the admin role. Pass the session token via Authorization: Bearer <token> header or cookies. Unauthenticated requests return 401.

What transport protocol does the MCP server use?​

Streamable HTTP — the standard MCP HTTP transport — in stateless mode. Send JSON-RPC messages via POST to /mcp; every request is authenticated and served independently, and no session ids are issued.

How many tools are available?​

The MCP server provides 9 tools, one per management area: product_management, order_management, assortment_management, users_management, filter_management, system_management, localization_management, provider_management, and quotation_management. Each tool takes an action argument selecting the operation. See the MCP Server Reference for the full list.

What resources does the MCP server expose?​

Three read-only resources for shop configuration:

  • unchained://shop/languages — Active languages
  • unchained://shop/currencies — Active currencies with decimal precision
  • unchained://shop/countries — Active countries

How are prices represented?​

All prices are integers. The decimal precision depends on the currency. For example, CHF has 2 decimal places, so a price of 1990 means 19.90 CHF. Always check the currencies resource for the correct number of decimals before interpreting or setting prices.

Should I validate localization entities before using them?​

Yes. Always read the MCP resources (languages, currencies, countries) before creating or referencing localization entities. This avoids errors from referencing entities that don't exist in the shop configuration.

Admin Copilot​

How do I enable the Admin Copilot?​

Pass a chat configuration with a model when connecting your server framework. See the Admin Copilot Setup for examples with OpenAI, Anthropic, and self-hosted models.

Can the Copilot generate images?​

Yes, if you configure imageGenerationTool in the chat options. The Copilot can then generate product and category images on request.

Can I add custom tools to the Copilot?​

Yes. Pass additional tools via the tools option in the chat configuration. These are added alongside the MCP tools. See Custom tools.

Can I customize the system prompt?​

Yes. Pass a system string in the chat configuration to override the default system prompt. The default prompt instructs the AI to validate resources before tool calls, handle prices as integers, and execute tools silently.

Integration Patterns​

How do I connect Claude Desktop to Unchained?​

Add an entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "unchained": {
      "url": "https://your-engine.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_TOKEN"
      }
    }
  }
}

See Connecting AI clients for Claude Code and Cursor examples.

Can I build a custom AI agent that manages my store?​

Yes. Connect with the AI SDK's MCP client (@ai-sdk/mcp) or plain JSON-RPC over HTTP from any language. See the Custom agents example.

Can I use the MCP server and GraphQL API together?​

Yes. The MCP server operates on the same core modules as the GraphQL API. Changes made through MCP tools are immediately visible via GraphQL and vice versa.

Troubleshooting​

I get a 401 error when connecting to the MCP server​

Verify that:

  1. Your token is valid and not expired
  2. The user associated with the token has the admin role
  3. The Authorization: Bearer <token> header is set correctly

The Copilot returns "NoSuchToolError"​

This means the AI tried to call a tool that doesn't exist. This can happen with models that hallucinate tool names. Try a more capable model or adjust your system prompt.

The Copilot returns "LimitExceeded"​

You've hit the rate limit of your AI model provider. Wait and retry, or switch to a provider with higher rate limits.

Prices look wrong (e.g., 1990 instead of 19.90)​

Prices are stored as integers. Divide by 10^(decimal places) for the currency. Check the currencies resource for the decimal precision of each currency.

The MCP connection drops after an engine restart​

The MCP server is stateless — there is no session to restore. Simply retry the request; as long as your token is still valid, it will be served.

I get a 403 "Invalid Origin" error​

Browser-originated requests are validated against the ROOT_URL hostname (plus localhost) to prevent DNS rebinding. Make sure ROOT_URL matches the host your client connects to, or omit the Origin header for non-browser clients.