MCP & 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.

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 · restart_site · stop_site
  • logs_site · stats_site · exec_site (admin)
  • export_site (tarball téléchargeable)

Databases

  • create_database · list_databases · get_database
  • attach_db_to_site · detach_db_from_site

Domains

  • add_domain · list_domains · remove_domain
  • verify_domain

Repos Git (Gitea interne)

  • create_repo (avec option initial_files)
  • list_repos · get_repo · delete_repo
  • link_repo_to_site (auto-deploy webhook)
  • push_files : commit multi-fichiers sans git local

Previews par commit

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

Backups

  • create_backup · list_backups · delete_backup

Auth

  • invite_user (admin) · request_magic_link · consume_magic_link
  • rotate_api_key (self ou admin)

Admin (role admin uniquement)

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

Restrictions et gotchas

Attention
Gitea est un backend interne. Les tools create_repo / list_repos ne retournent pas d'URL Gitea pour les clients (redact). Utilise push_files pour écrire du code, pas git push HTTPS depuis Claude Desktop (souvent bloqué par le proxy réseau du client).
Astuce
Les IDs internes (project_id, user_id) sont optionnels quand ils peuvent être auto-résolus (un seul project owned, self-rotate, etc.). Ton agent ne devrait jamais te demander un ID interne.

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