Humind MCP server

Connect Claude, or any MCP-compatible AI agent, directly to your Humind store. One endpoint, your existing API key, and an agent can read your settings, pull analytics, search conversations, manage your knowledge base, and browse your catalog: the same operations available through the public REST API, exposed as tools an LLM can call.

What is MCP?

Model Context Protocol is an open standard for connecting AI applications to external tools and data. If you already use Claude Code, Claude Desktop, or another MCP client, adding Humind is the same "add a server" flow you use for any other integration.

Endpoint

https://api.thehumind.com/public/mcp

• Transport: Streamable HTTP.
• Session model: stateless. Every request is self-contained, there's no session to keep alive or reconnect. Only POST is supported; GET/DELETE (session-management verbs in the spec) return 405.
• Auth: the exact same Bearer hmd_* API key you use for the REST API. No separate MCP credential to generate.

Authentication

Generate a key from your dashboard at Settings → Developer → Credentials, exactly as described in Authentication. Pass it as a standard bearer token:

Authorization: Bearer hmd_live_aB3xK9qLm2pR7sT5wY8zN1_4f7c2e9a

There's nothing MCP-specific about the credential: the same key you use to curl /public/v1/products works here.

The tool catalog

Seventeen tools, grouped by the same scopes as the REST API. A tool only appears in tools/list if your key holds the scope it needs: the catalog adapts automatically, so an agent connected with a read-only key never even sees update_settings or upsert_knowledge as an option, rather than seeing it and getting a 403.

Tool	Required scope	What it does
get_store_overview	(none, any valid key)	Company name, configured locales, default currency/country, the scopes granted to this key, live counters (products, knowledge documents, conversations), last catalog sync, and whether the widget is installed.
get_setup_status	(none, any valid key)	Onboarding checklist of the store: which setup steps are done and, for each remaining one, the suggested action, including which MCP tool can complete it.
search_docs	(none, any valid key)	Keyword search over this developer documentation (guides, API reference, troubleshooting), in English or French.
get_doc_page	(none, any valid key)	Full markdown of one documentation page, by the path returned by search_docs.
list_settings	settings:read	Current value of every merchant setting.
get_settings_schema	settings:read	The machine-readable contract of every setting (key, type, bounds); call this before update_settings.
update_settings	settings:write	Update one or more settings in a single all-or-nothing call.
search_conversations	conversations:read	List or free-text search visitor conversations, with the same filters as the REST endpoint.
get_conversation	conversations:read	Full transcript of one conversation, optionally with the identified contact.
get_kpis	analytics:read	Key metrics over a period, with trend.
get_top_questions	analytics:read	Clustered visitor questions: volume, trend, unanswered rate.
list_products	catalog:read	Products in the catalog, paginated.
get_product	catalog:read	One product with variants, translations, images.
list_knowledge	knowledge:read	Knowledge-base documents the AI grounds its answers on.
get_knowledge	knowledge:read	One knowledge document with its full content.
upsert_knowledge	knowledge:write	Create or update a knowledge document by external_id.
delete_knowledge	knowledge:write	Archive (default) or permanently delete a knowledge document.

This documentation is part of the server

An agent connected to the MCP server does not need to browse this site: search_docs and get_doc_page serve these very pages (both languages) directly as tools, so it can answer "how do I install the widget?" or "what does this scope cover?" from the official source. The raw markdown behind them is also public, at /raw/index.json and /llms.txt, for any other AI tooling you use. This site is the single source of truth: the MCP server reads the published pages at runtime (with a server-side cache of about an hour), so what the tools serve is always this documentation, at most an hour behind.

Every call goes through the documented API

Each tool delegates to the exact same controller, validation, and tenant scoping as its REST counterpart: same DTOs, same audit log. Reading a tool's behavior in the API reference tells you exactly what the tool does; there's no separate MCP-only logic to learn.

Argument shapes

Every tool ships its exact input schema in tools/list, and a wrong guess returns a validation error listing what was expected, so an agent always self-corrects. But four shapes are easy to guess wrong on the first call; passing them right saves a round-trip:

• upsert_knowledge takes the document wrapped in a document object, not flat fields:

{ "document": { "external_id": "faq-returns", "type": "snippet", "title": "Return policy", "content": "Returns are accepted within 30 days." } }

• get_knowledge and delete_knowledge take document_id (a Humind id or api:<external_id>), not knowledge_id:

{ "document_id": "api:faq-returns" }

• get_kpis takes a period enum (today, 7_days, 30_days, 90_days, year, total, or custom with start_date / end_date), same as the REST endpoint:

{ "period": "30_days" }

• get_top_questions takes explicit start_date and end_date (YYYY-MM-DD); there is no period shortcut:

{ "start_date": "2026-06-29", "end_date": "2026-07-29" }

Connect a client

Claude Code

claude mcp add --transport http humind https://api.thehumind.com/public/mcp \
  --header "Authorization: Bearer hmd_live_aB3xK9qLm2pR7sT5wY8zN1_4f7c2e9a"

Generic MCP client (JSON config)

Any client that reads a standard mcpServers block (Claude Desktop, and most other MCP hosts) accepts:

{
  "mcpServers": {
    "humind": {
      "type": "http",
      "url": "https://api.thehumind.com/public/mcp",
      "headers": {
        "Authorization": "Bearer hmd_live_aB3xK9qLm2pR7sT5wY8zN1_4f7c2e9a"
      }
    }
  }
}

claude.ai

If your claude.ai plan supports custom connectors, add one pointing at the endpoint above with the Authorization header set to your key. The URL and header are all a compliant client needs; check your plan's connector settings for where to enter them.

Treat the key like a password

Anywhere you paste your API key (a client config file, an environment variable, a claude.ai connector setting), treat it exactly like you would in a REST integration. Never commit it to a repo or share it outside your secret store. See If a key leaks.

Best practices

• Mint a dedicated key for the MCP connection, separate from the one your backend or CI uses. If an agent misbehaves or a client is compromised, you revoke one key without touching your production integration.
• Scope it to the minimum the agent needs. An agent that only reads analytics and answers "how's the store doing" questions needs analytics:read and nothing else; it shouldn't hold knowledge:write or settings:write just in case. Remember scopes are immutable after creation: pick narrow, and mint a new key later if you need more.
• Revoke it the same way you'd revoke any other key: from Settings → Developer → Credentials in your dashboard. Revocation reaches the API edge within at most 60 seconds.

Next

• Authentication: generate and manage the key you'll use here.
• Settings: the REST surface behind list_settings / update_settings.
• Analytics: the REST surface behind get_kpis / get_top_questions.
• Conversations: the REST surface behind search_conversations / get_conversation.