Aller au contenu principal

Authentification MCP

Chaque requête vers Copera MCP Cloud porte un bearer token dans l'en-tête Authorization :

Authorization: Bearer <token>

Copera MCP Cloud transmet le token à la Copera Public API, qui le valide. Le serveur lui-même ne stocke pas d'identifiants — c'est un proxy sans état. Deux types de tokens sont acceptés.

Types de tokens​

PréfixeTypeComment l'obtenir
cp_pat_…Personal Access Token (PAT)Créé manuellement dans les paramètres de votre workspace Copera. Vous le collez dans la configuration du client.
cp_oat_…Token OAuth MCPCréé automatiquement par le flux OAuth lorsqu'un client se connecte sans token.

Personal Access Tokens (cp_pat_)​

Un PAT est le moyen le plus simple de se connecter. Vous le créez une fois dans Copera, lui accordez des scopes, et le collez dans la configuration de votre client MCP (voir Connexion). Le PAT agit en votre nom dans les scopes que vous avez accordés.

Les PAT sont idéaux pour :

  • Les clients qui acceptent un en-tête Authorization statique.
  • Les configurations personnelles/locales où vous contrôlez le fichier de configuration.
  • Les scripts et tests avec le MCP Inspector.

Pour le modèle PAT complet, les scopes et le cycle de vie, voir le guide d'authentification de l'API.

MCP OAuth (cp_oat_)​

Les clients compatibles OAuth (comme les connecteurs distants de Claude) peuvent s'authentifier sans token collé. Lorsque le client appelle d'abord le serveur sans bearer valide, le serveur renvoie un 401 portant un challenge de découverte, et le client suit le flux OAuth pour obtenir un token cp_oat_… de courte durée. L'utilisateur approuve les scopes demandés sur un écran de consentement Copera, et le client stocke et rafraîchit le token de façon transparente.

OAuth est idéal pour :

  • Les utilisateurs finaux qui ne doivent pas manipuler de tokens bruts.
  • Les clients avec une prise en charge native des connecteurs distants.
  • L'octroi uniquement des scopes consentis par l'utilisateur, par connexion.

Le flux OAuth​

Le serveur implémente la spécification d'autorisation MCP au-dessus des métadonnées de ressource protégée OAuth 2.0.

1. Client → MCP server: POST /mcp  (no / invalid bearer)
2. MCP server → Client: 401 Unauthorized
     WWW-Authenticate: Bearer
       resource_metadata="https://mcp.copera.ai/.well-known/oauth-protected-resource/mcp"
       scope="access_boards access_channels access_docs access_drive access_notifications"
3. Client fetches the resource-metadata document to discover the authorization server.
4. Client runs the OAuth authorization flow against Copera, user consents to scopes.
5. Client receives a cp_oat_… token and retries POST /mcp with it.
6. MCP server validates the token with the API and proxies the tool call.

Métadonnées de ressource protégée​

Le serveur publie les métadonnées de ressource protégée OAuth 2.0 à deux chemins well-known :

  • https://mcp.copera.ai/.well-known/oauth-protected-resource
  • https://mcp.copera.ai/.well-known/oauth-protected-resource/mcp

Le document annonce la ressource, le serveur d'autorisation et les scopes pris en charge :

{
  "resource": "https://mcp.copera.ai/mcp",
  "authorization_servers": ["https://api.copera.ai"],
  "scopes_supported": [
    "access_boards",
    "access_channels",
    "access_docs",
    "access_drive",
    "access_notifications"
  ],
  "bearer_methods_supported": ["header"]
}

Le challenge WWW-Authenticate​

Un POST /mcp non authentifié renvoie 401 avec un challenge conforme à la spécification afin que les clients MCP puissent démarrer le flux automatiquement :

WWW-Authenticate: Bearer resource_metadata="https://mcp.copera.ai/.well-known/oauth-protected-resource/mcp" scope="access_boards access_channels access_docs access_drive access_notifications"
Les tokens OAuth sont introspectés à chaque appel

Pour les tokens cp_oat_…, le serveur valide le token contre l'endpoint d'introspection de l'API avant de proxifier. Un token OAuth inactif ou révoqué est rejeté avec un 401. Les PAT (cp_pat_…) sont validés en aval par la Public API elle-même.

Scopes et mapping vers les outils​

Copera MCP Cloud prend en charge cinq scopes OAuth. Chaque scope débloque une famille d'outils ; un token auquel manque le scope requis obtient un 403 lorsqu'il appelle un outil de cette famille.

ScopeDébloqueOutils
access_boardsBoards, tables, lignes, commentaires, exportslist_boards, get_board, list_tables, get_table_schema, list_rows, get_row, create_row, update_row, delete_row, get_row_markdown, set_row_markdown, list_row_comments, add_row_comment, get_row_attachment_url, export_table
access_docsDocumentssearch_docs, get_docs_tree, get_doc, get_doc_content, create_doc, set_doc_content, update_doc_metadata, delete_doc
access_channelsChannels de chat et messages directslist_channels, send_message
access_notificationsNotificationslist_notifications, update_notification, delete_notification
access_driveFichiers et dossiers du driveget_drive_tree, search_drive, get_drive_item, get_drive_download_url, create_drive_folder
Outils workspace et search

get_workspace_info, list_workspace_members, list_workspace_teams et l'outil cross-entité search sont au niveau workspace et ne renvoient que ce que le token est autorisé à voir — search filtre les résultats selon les permissions du token.

Un 403 signifie généralement un scope manquant

Si un outil renvoie 403 Forbidden, le token n'a très probablement pas le scope requis. Accordez le scope sur le PAT, ou re-consentez la connexion OAuth avec le scope supplémentaire.

Certains outils — documents et drive en particulier — sont PAT uniquement au niveau de la Public API : les clés d'intégration ne peuvent pas y accéder. En cas de doute, utilisez un Personal Access Token avec les scopes nécessaires.

Voir aussi​