Importer des données avec le serveur MCP Puwapi (Work & CRM)

En plus du serveur MCP dédié à Knowledge (voir Piloter Knowledge avec le serveur MCP), Puwapi fournit un serveur MCP transversal (@puwapi/mcp) qui permet à un agent IA (Claude Code, Claude Desktop…) d'importer et gérer des données dans deux modules :

• Work — projets, tâches et tickets (référence auto KEY-N) ;
• Hub CRM — contacts et opportunités (deals) du pipeline commercial.

Cas d'usage typique : migrer un ancien outil (« importe ces 400 contacts et leurs deals », « recrée ce backlog Jira dans Work ») en collant simplement les données à un agent.

1. Les clés API¶

Chaque module s'authentifie par sa propre clé API tenant (X-Server-API-Key). Vous pouvez n'en configurer qu'une : les outils de l'autre module renverront une erreur explicite au lieu de casser la session.

Module	Préfixe	Gestion (JWT)	Surface d'intégration
Work	pwk_live_…	/api/work/keys	api/public/work
Hub CRM	phk_live_…	/api/hub/keys	api/public/hub

Scopes read / write — les imports exigent une clé write. La clé en clair n'est affichée qu'une fois (hash SHA-256 en base).

2. Brancher dans Claude Code¶

claude mcp add puwapi \
  -e PUWAPI_WORK_API_KEY=pwk_live_xxx \
  -e PUWAPI_HUB_API_KEY=phk_live_xxx \
  -- node /chemin/vers/mcp/dist/index.js

En dev local, ajoutez PUWAPI_WORK_API_URL / PUWAPI_HUB_API_URL (défauts = prod).

3. Outils exposés¶

Outil	Scope	Rôle
work_list_projects · work_list_items	read	inventorier l'existant
work_create_project · work_create_item	write	création unitaire
work_import_items	write	import en masse de tâches/tickets
hub_list_customers	read	inventorier les contacts
hub_import_customers	write	import en masse de contacts
hub_import_deals	write	import en masse d'opportunités

Les imports passent par les endpoints bulk des surfaces d'intégration (POST api/public/work/{projects,items}/bulk, POST api/public/hub/{customers,deals}/bulk) — utilisables aussi directement en REST si vous préférez scripter.

4. Quelle surface pour quel besoin ?¶

• Serveur MCP Knowledge (@puwapi/knowledge-mcp) : rédiger et organiser de la documentation (20 outils, clé pkk_live_…).
• Serveur MCP Puwapi (@puwapi/mcp) : imports et gestion Work + CRM.
• REST direct : mêmes clés, mêmes surfaces api/public/* — voir Clés API serveur.