NabuDesk MCP server

Drives NabuDesk conversationally instead of through the Livewire panel: create a business, write its knowledge base, and check what the support bot would answer — without opening a browser or reaching for docker exec.

MCP client (Claude Code / Claude Desktop)
   │ stdio
   ▼
mcp-server/index.js                     ← runs locally
   │ HTTPS + X-Internal-Token
   ▼
NabuDesk  /api/internal/v1/*            ← app/Http/Controllers/Api/Internal
   │
   ▼
BusinessProvisioningService · KnowledgeSyncService · SupportDryRunService

The MCP server holds no business logic. It is a transport adapter over the operator API, so the panel and the API cannot drift apart.

Security

INTERNAL_API_TOKEN is a single shared secret that is not scoped to a business — it can read and write every business on the instance. It is for staff only. Never hand it to a customer, and never put it in a client-side app.

When the variable is unset the entire /api/internal/* surface returns 503, so a deploy that forgets the secret fails closed rather than serving the API unauthenticated.

Related MCP server: rbac-rag-assistant

Setup

On the NabuDesk instance, set the secret (in Coolify's environment variables, so it survives a redeploy — a value written only into the container's .env is lost on the next deploy):

openssl rand -hex 32
# → INTERNAL_API_TOKEN=<value>

Locally:

cd mcp-server
npm install
npm run build

Register it with your MCP client. For Claude Code:

claude mcp add nabudesk \
  --env NABUDESK_URL=https://desk.nabuxai.com \
  --env NABUDESK_TOKEN=<the same value> \
  -- node /absolute/path/to/NabuDesk/mcp-server/index.js

Or in claude_desktop_config.json:

{
  "mcpServers": {
    "nabudesk": {
      "command": "node",
      "args": ["/absolute/path/to/NabuDesk/mcp-server/index.js"],
      "env": {
        "NABUDESK_URL": "https://desk.nabuxai.com",
        "NABUDESK_TOKEN": "<the same value>"
      }
    }
  }
}

Tools

Businesses

Custom Domains & Zone Mapping

Knowledge

Diagnostics

Why test_retrieval exists

The failure it catches is silent. EmbeddingService::searchKnowledge() drops anything below a 0.2 minimum score. The embedding model is cross-lingual but weak: a non-English question can rank the correct document first and still score under the threshold, so nothing is retrieved and the bot answers from the context alone — confidently, and without the specifics.

Measured on the Zooey Support knowledge base before it was made trilingual:

Writing the knowledge in the languages customers actually use raised the failing case to 0.297. test_retrieval is how you see that, since ask alone still returns a plausible-looking answer.

Why upsert_knowledge returns two counts

EmbeddingService::embedMany never throws. It returns null for any text it could not embed — including when the provider key is unset or the request failed. Without counting, every row is written with a null vector and reported as a success while being permanently unretrievable.

written is how many rows were stored; embedded is how many of them can actually be found. They should match. If nothing could be embedded the call returns 503 and writes nothing, because a business with knowledge it can never retrieve is worse than a failed call it can retry.

Notes

• ask is a dry run. It shares production's retrieval, business context and model, but not the prompt-injection guard or the per-contact reply budget — those belong to the live ReplyComposer path.

• upsert_business is idempotent by (owner, name), and upsert_knowledge by title. Both are safe for an AI caller that retries.

• The Livewire create form still assembles its AI context inline. Until it is refactored onto BusinessProvisioningService, a change to the section list must be mirrored in resources/views/livewire/pages/businesses/create.blade.php.