MCP et Claude Desktop

Iridflow expose un serveur MCP (Model Context Protocol). Tu peux le brancher à Claude Desktop, Claude Code ou n'importe quel client MCP, et piloter Iridflow en langage naturel.

Setup en 3 étapes

1. Génère une API key sur /me → rotate key. Note-la (format iridflow_live_...).
2. Ouvre la config MCP de ton client :
   • Claude Desktop : ~/.claude/mcp.json (ou via Réglages → Extensions → MCP)
   • Claude Code : idem
3. Ajoute Iridflow :

   // mcp.json
   {
     "mcpServers": {
       "iridflow": {
         "url": "https://mcp.iridflow.com/mcp",
         "headers": {
           "x-api-key": "iridflow_live_..."
         }
       }
     }
   }

Redémarre Claude Desktop. Tu devrais voir ~52 tools Iridflow disponibles.

Bonus · installer le Skill Iridflow (Claude Code seulement)

Le skill donne un guide contextuel à Claude Code (mots-clés déclenchants, cheatsheet workflow, pièges connus). Optionnel - le tool get_iridflow_guide couvre 90% du besoin - mais évite un round-trip MCP au premier usage.

// Terminal
mkdir -p ~/.claude/skills/iridflow
curl -o ~/.claude/skills/iridflow/SKILL.md https://iridflow.com/skill/iridflow

Une fois installé, Claude Code invoquera automatiquement le skill quand tu parleras de créer/déployer/backuper un site, choisir un runtime, restaurer un backup, etc.

Workflow recommandé

Le premier réflexe de l'agent doit être whoami pour connaître ton user + projets :

whoami() → {
  user_id: "user_xxx",
  email: "toi@example.com",
  role: "client",
  projects_count: 1,
  projects: [{ id: "proj_xxx", slug: "mon-projet", name: "Mon Projet" }]
}

Ensuite l'agent peut créer sans jamais demander d'IDs internes :

// Conversation type
Toi : "Crée-moi un site Next.js appelé blog"

Claude : appelle create_site({ name: "blog", runtime: "nextjs" })
         → project_id auto-résolu vers ton seul project
         → site créé, URL retournée

Tools disponibles (52+)

Catégories principales, tous les tools sont documentés dans l'API MCP tools/list :

Identity

• whoami : identité + projects owned

Projects

• create_project · list_projects · get_project
• delete_project · update_project_owner (admin)

Sites

• create_site · list_sites · get_site · delete_site
• deploy_site (pull la source liée via link_repo_to_site avant compose up --build) · restart_site · stop_site
• logs_site · stats_site · exec_site (admin)
• export_site (tarball téléchargeable 24h)
• change_site_runtime (admin, destructif : wipe siteDir + starter frais)

Marketplace templates (one-click)

• list_templates (WordPress, Ghost, Umami, Plausible, Directus, n8n, Metabase, Uptime Kuma, Vaultwarden, Next.js starter)
• create_site_from_template (orchestre create_site + create_database + attach)

Databases

• create_database · list_databases · get_database
• attach_db_to_site · detach_db_from_site
• delete_database (avec cleanup env vars override des sites attachés)

Domains

• add_domain · list_domains · remove_domain
• verify_domain · set_domain_redirect

Repos Git (Gitea interne)

• create_repo (avec option initial_files)
• list_repos · get_repo · delete_repo
• link_repo_to_site : persiste sourceRepo/sourceBranch/autoDeploy sur le site (vérifiable via get_site) et pose un webhook Gitea. Idempotent : rappelable sans dupliquer le webhook.
• push_files : commit multi-fichiers sans git local (jusqu'à 180 Mo bruts). Accepte content_utf8 (texte) OU content_b64 (binaires) par fichier. operation=delete avec auto_sha=true pour supprimer.
• get_repo_file : lit un fichier (retourne content_utf8 + content_b64 + sha + size en octets)
• list_repo_tree : arborescence complète (path, type, size en octets, sha)
• list_repo_commits : N derniers commits (pour choisir un SHA à deployer)

Previews par commit

• deploy_preview · list_previews · stop_preview · delete_preview
• pin_preview · preview_gc · preview_logs

Backups (Nextcloud WebDAV)

• create_backup · list_backups · delete_backup
• set_backup_schedule : toggle cron daily 03:00 UTC par site (retention 30j auto-purge)
• restore_backup : télécharge + wipe volumes + remise à l'état backup (DESTRUCTIF)

Auth

• invite_user (admin, magic link valable 24h)
• request_magic_link · consume_magic_link (magic link valable 15 min)
• rotate_api_key (self ou admin)

Guide (pour agents IA)

• get_iridflow_guide : retourne le guide complet (workflow, runtimes, pièges). À appeler AVANT create_site pour choisir le bon runtime.

Admin (role admin uniquement)

• list_users · create_user · delete_user · update_user_role
• list_audit_log · audit_stats · admin_stats

Restrictions et gotchas

Auth MCP

• L'API key est passée en header x-api-key, jamais dans le body
• Chaque appel MCP est audité côté serveur (voir /admin/audit si tu es admin)
• Le RBAC est appliqué : un client ne peut pas voir/toucher les ressources d'un autre user

Rate limits

Actuellement pas de rate limit strict sur les tools MCP. Contactez l'admin en cas d'abus.

Debug

Si un tool ne marche pas :

1. Vérifie l'endpoint : curl https://mcp.iridflow.com/health
2. Vérifie ton auth : curl -H "x-api-key: ..." https://mcp.iridflow.com/api/v1/whoami
3. Regarde le message d'erreur du tool (généralement explicite)
4. Si invalid api key : ta clé a été rotate → /me pour en générer une nouvelle