Mankomail

Connecter un client ​

Tout client MCP a besoin des deux mêmes choses : l’adresse du point de terminaison, <PUBLIC_BASE_URL>/api/v1/mcp, et une clé d’API envoyée dans l’en-tête Authorization: Bearer. Cette page donne la configuration des clients les plus courants et une session curl brute pour vérifier une instance à la main.

Créer la clé ​

  1. Ouvrez Réglages › Clés d’API et cliquez sur Nouvelle clé.
  2. Donnez-lui un nom qui dise quel client la détient, par exemple « Claude Desktop, portable ».
  3. Choisissez les portées. Pour chaque domaine : rien, lire seulement, ou lire et écrire.
    • Exploration en lecture seule : workflows:read, executions:read, mailboxes:read, connections:read, tables:read. L’assistant peut décrire, chercher, diagnostiquer et proposer, mais n’écrit rien.
    • Construction de workflows : les mêmes, avec workflows:write à la place de workflows:read. L’assistant peut aussi créer des brouillons, les modifier et publier. N’ajoutez tables:write que si le membre est administrateur et veut que l’assistant crée des tables.
  4. Copiez la clé quand elle s’affiche : elle commence par mk_ et n’est montrée qu’une fois. Mankomail n’en garde qu’une empreinte.

Une clé n’accorde jamais plus que ce que son membre possède ; voir Portées et tools et Portées de l’API pour la grammaire. Révoquez la clé depuis la même page quand le client n’en a plus besoin : le refus est immédiat.

Claude Code ​

Déclarez le serveur avec le transport http et la clé en en-tête :

sh
claude mcp add --transport http <nom> <PUBLIC_BASE_URL>/api/v1/mcp \
  --header "Authorization: Bearer mk_…"

Remplacez <nom> par le nom que vous voulez voir dans Claude Code, par exemple celui de votre instance. Le même serveur peut être déclaré pour un projet dans son .mcp.json :

json
{
  "mcpServers": {
    "<nom>": {
      "type": "http",
      "url": "<PUBLIC_BASE_URL>/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer mk_…"
      }
    }
  }
}

Évitez de versionner un fichier qui contient la clé : préférez la commande, qui enregistre le serveur dans votre configuration d’utilisateur, ou gardez le fichier de projet hors du gestionnaire de versions.

Cursor ​

Cursor lit .cursor/mcp.json dans le projet (ou ~/.cursor/mcp.json pour tous les projets). Un serveur distant se déclare avec url et headers :

json
{
  "mcpServers": {
    "<nom>": {
      "url": "<PUBLIC_BASE_URL>/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MANKO_MCP_KEY}"
      }
    }
  }
}

Cursor documente l’interpolation ${env:NOM} dans headers : la clé peut donc vivre dans la variable d’environnement MANKO_MCP_KEY plutôt que dans le fichier. Une valeur littérale "Bearer mk_…" fonctionne aussi.

Claude Desktop ​

Claude Desktop ajoute les serveurs distants par Réglages › Connecteurs › Ajouter un connecteur personnalisé, un parcours où le serveur mène l’authentification, en général par OAuth. Mankomail s’authentifie par un en-tête fixe ; la voie vérifiée est donc le pont mcp-remote : un petit programme local que Claude Desktop lance comme serveur stdio et qui transmet chaque message au point de terminaison distant avec votre en-tête.

Modifiez claude_desktop_config.json (Réglages › Développeur › Modifier la configuration) et ajoutez :

json
{
  "mcpServers": {
    "<nom>": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "<PUBLIC_BASE_URL>/api/v1/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer mk_…"
      }
    }
  }
}

Deux détails viennent de la documentation de mcp-remote : la valeur de l’en-tête passe par une variable d’environnement parce que certains clients abîment les espaces dans args, d’où Authorization:${AUTH_HEADER} sans espace ; et mcp-remote essaie Streamable HTTP en premier par défaut (--transport http-first), ce que parle Mankomail. Redémarrez Claude Desktop après l’enregistrement ; les tools apparaissent sous le nom du serveur.

npx suppose Node.js sur la machine. Si un client que vous employez se connecte directement aux serveurs Streamable HTTP distants avec des en-têtes personnalisés, préférez-le au pont.

À la main, avec curl ​

Une session brute montre ce que fait un client. Chaque message est une requête JSON-RPC dans un POST, avec la clé, Content-Type: application/json et un en-tête Accept qui liste à la fois application/json et text/event-stream, comme l’exige le transport.

1. Initialiser. Le serveur répond avec son nom, la marque de l’instance en titre, sa version et ses capacités :

sh
curl -s <PUBLIC_BASE_URL>/api/v1/mcp \
  -H "Authorization: Bearer mk_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "0" }
    }
  }'

Le transport étant sans état, la réponse ne porte aucun Mcp-Session-Id, et le message notifications/initialized que les clients envoient normalement ensuite n’est pas nécessaire entre deux appels curl : rien n’est conservé côté serveur de toute façon.

2. Lister les tools. Envoyez la version négociée dans MCP-Protocol-Version :

sh
curl -s <PUBLIC_BASE_URL>/api/v1/mcp \
  -H "Authorization: Bearer mk_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

Le résultat ne liste que les tools que les portées de la clé autorisent. Chacun porte un name (workflow_list), un title avec le nom interne (workflow.list), une description qui se termine par la portée exigée, un inputSchema, un outputSchema quand la sortie est un objet, et des annotations (readOnlyHint, destructiveHint: false, openWorldHint: false).

3. Appeler un tool. Les arguments suivent l’inputSchema du tool :

sh
curl -s <PUBLIC_BASE_URL>/api/v1/mcp \
  -H "Authorization: Bearer mk_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": { "name": "workflow_list", "arguments": { "includeArchived": false } }
  }'

Un résultat réussi porte la sortie deux fois : en texte JSON dans content[0].text et en objet dans structuredContent. Un refus revient comme un résultat avec isError: true et { "error": { "code", "message" } }, voir Portées et tools.

Sans clé valide, le point de terminaison répond 401 avec le format d’erreur de l’API avant de lire le moindre message MCP. GET ou DELETE sur le point de terminaison répondent 405.

Pages liées ​