> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colismove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Configurez ColisMove MCP dans votre environnement de développement en moins de 2 minutes.

## Prérequis

Vous avez besoin de l'un de ces outils IA installé :

* [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (recommandé)
* [Cursor](https://cursor.sh)
* [Windsurf](https://codeium.com/windsurf)
* Tout client compatible MCP

## Obtenir votre token API

ColisMove MCP utilise un **portail self-service** pour gérer les tokens API personnels : [https://mcp-portal.colismove.com](https://mcp-portal.colismove.com).

<Steps>
  <Step title="Demander un accès">
    Envoyez votre adresse email professionnelle à votre tech lead afin qu'un workspace soit créé pour vous. Vous recevrez un email d'invitation depuis `noreply@mail.app.supabase.io`.
  </Step>

  <Step title="Configurer votre compte">
    Cliquez sur le lien dans l'email d'invitation, définissez un mot de passe : vous serez redirigé vers votre tableau de bord à [mcp-portal.colismove.com/dashboard](https://mcp-portal.colismove.com/dashboard).
  </Step>

  <Step title="Générer un token">
    Ouvrez la page **Tokens**, cliquez sur **Create a token**, donnez-lui un nom (par exemple `MacBook Pro — Claude Code`) et copiez le token affiché à l'écran.

    Le token est au format `cmcp_<64 hex chars>`.

    <Warning>
      Le token complet est **affiché une seule fois**. Si vous le perdez, révoquez-le depuis le tableau de bord et générez-en un nouveau.
    </Warning>
  </Step>

  <Step title="Limites de tokens">
    Vous pouvez avoir jusqu'à **3 tokens actifs** simultanément. Révoquez les tokens inutilisés depuis le tableau de bord avant d'en créer un nouveau.

    Bonne pratique : un token par machine ou par outil IA (Claude Code, Cursor, etc.).
  </Step>
</Steps>

## Configuration

Remplacez `YOUR_API_TOKEN` ci-dessous par la valeur `cmcp_...` générée sur le portail.

<Tabs>
  <Tab title="Claude Code">
    ### Option 1 : commande CLI (la plus rapide)

    ```bash theme={null}
    claude mcp add colismove-mcp \
      --transport http \
      --url https://colismove-mcp.onrender.com/mcp \
      --header "Authorization: Bearer YOUR_API_TOKEN"
    ```

    Ajoutez `--scope user` pour rendre le serveur accessible depuis n'importe quel répertoire de projet.

    ### Option 2 : fichier de config au niveau projet

    Créez `.mcp.json` à la racine de votre projet :

    ```json theme={null}
    {
      "mcpServers": {
        "colismove-mcp": {
          "type": "http",
          "url": "https://colismove-mcp.onrender.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_TOKEN"
          }
        }
      }
    }
    ```

    ### Option 3 : global (tous les projets)

    Créez `~/.claude/.mcp.json` :

    ```json theme={null}
    {
      "mcpServers": {
        "colismove-mcp": {
          "type": "http",
          "url": "https://colismove-mcp.onrender.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_TOKEN"
          }
        }
      }
    }
    ```

    <Tip>
      Utilisez l'option globale si vous voulez disposer du contexte ColisMove depuis n'importe quel répertoire de projet.
    </Tip>
  </Tab>

  <Tab title="Cursor">
    Ouvrez Cursor Settings → MCP → Add new server :

    * **Name** : `colismove-mcp`
    * **Type** : `HTTP`
    * **URL** : `https://colismove-mcp.onrender.com/mcp`
    * **Headers** :
      ```
      Authorization: Bearer YOUR_API_TOKEN
      ```
  </Tab>

  <Tab title="Windsurf">
    Ajoutez à votre `.windsurfrules` ou à votre configuration MCP :

    ```json theme={null}
    {
      "mcpServers": {
        "colismove-mcp": {
          "type": "http",
          "url": "https://colismove-mcp.onrender.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_TOKEN"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Utilisez ces informations de connexion avec n'importe quel client compatible MCP :

    | Paramètre       | Valeur                                   |
    | --------------- | ---------------------------------------- |
    | **Transport**   | Streamable HTTP                          |
    | **URL**         | `https://colismove-mcp.onrender.com/mcp` |
    | **Auth header** | `Authorization: Bearer YOUR_API_TOKEN`   |
  </Tab>
</Tabs>

## Utiliser des variables d'environnement (recommandé)

Pour éviter de coder en dur votre token, utilisez une variable d'environnement :

```json theme={null}
{
  "mcpServers": {
    "colismove-mcp": {
      "type": "http",
      "url": "https://colismove-mcp.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer ${COLISMOVE_MCP_TOKEN}"
      }
    }
  }
}
```

Définissez ensuite la variable dans votre profil shell (`~/.zshrc` ou `~/.bashrc`) :

```bash theme={null}
export COLISMOVE_MCP_TOKEN="cmcp_your_token_here"
```

## Vérifier la connexion

Après la configuration, redémarrez votre outil IA et vérifiez :

<Tabs>
  <Tab title="Claude Code">
    Tapez `/mcp` dans Claude Code. Vous devriez voir `colismove-mcp` avec un statut vert.

    Essayez ensuite :

    ```
    What endpoints exist for bookings?
    ```
  </Tab>

  <Tab title="Cursor / Windsurf">
    Ouvrez un nouveau chat et demandez :

    ```
    What is ColisMove's reservation flow?
    ```

    L'assistant devrait utiliser les outils MCP pour répondre avec des informations détaillées et précises.
  </Tab>
</Tabs>

## Gérer vos tokens

Rendez-vous à tout moment sur [mcp-portal.colismove.com/dashboard/tokens](https://mcp-portal.colismove.com/dashboard/tokens) pour :

* Voir vos tokens actifs (nom, préfixe `cmcp_xxxxxxxxxxxx`, date de dernière utilisation)
* **Révoquer** un token instantanément (recommandé en cas de fuite ou de perte de machine)
* Créer un nouveau token (jusqu'à 3 tokens actifs)

<Warning>
  La révocation prend jusqu'à 60 secondes pour se propager (cache côté serveur). Au-delà, toute requête utilisant le token révoqué renverra `403 Invalid or revoked token`.
</Warning>

## Dépannage

<AccordionGroup>
  <Accordion title="Le serveur ne se connecte pas">
    * Vérifiez que l'URL est exactement `https://colismove-mcp.onrender.com/mcp` (sans slash final)
    * Vérifiez que votre token commence par `cmcp_` et n'a pas été tronqué à la copie
    * Le serveur peut mettre \~30 secondes à démarrer à la première requête (offre Render gratuite)
  </Accordion>

  <Accordion title="Les outils n'apparaissent pas">
    * Redémarrez votre outil IA après avoir ajouté la configuration
    * Dans Claude Code, exécutez `/mcp` pour vérifier le statut du serveur
    * Assurez-vous que le fichier `.mcp.json` est à la racine du projet ou dans `~/.claude/`
  </Accordion>

  <Accordion title="Erreur d'authentification (401/403)">
    * `401 Missing Authorization` → l'en-tête `Authorization: Bearer ...` est manquant ou vide
    * `403 Invalid or revoked token` → le token n'existe pas, a été révoqué ou a expiré. Générez-en un nouveau sur le [portail](https://mcp-portal.colismove.com/dashboard/tokens).
    * Vérifiez que le format de l'en-tête est `Bearer YOUR_TOKEN` (avec une espace après `Bearer`)
    * Si vous avez committé votre token par erreur dans git, révoquez-le immédiatement depuis le portail
  </Accordion>

  <Accordion title="J'ai perdu mon token">
    Les tokens sont hachés côté serveur et ne peuvent pas être récupérés. Rendez-vous sur le [portail](https://mcp-portal.colismove.com/dashboard/tokens), révoquez celui qui est perdu, puis générez un nouveau token.
  </Accordion>

  <Accordion title="Je n'arrive pas à me connecter au portail">
    * Assurez-vous d'utiliser l'adresse email fournie lors de votre demande d'accès
    * Utilisez le lien **Forgot password** sur la page de connexion
    * Si vous n'avez jamais reçu l'email d'invitation, vérifiez vos spams puis demandez à votre tech lead de le renvoyer
  </Accordion>

  <Accordion title="Réponses lentes">
    Le serveur MCP tourne sur l'offre gratuite de Render. La première requête après une période d'inactivité peut prendre 30 à 60 secondes le temps que le serveur démarre. Les requêtes suivantes sont rapides.
  </Accordion>
</AccordionGroup>