Vai al contenuto principale

Autenticazione MCP

Ogni richiesta a Copera MCP Cloud porta un bearer token nell'header Authorization:

Authorization: Bearer <token>

Copera MCP Cloud inoltra il token alla Copera Public API, che lo valida. Il server stesso non memorizza credenziali — è un proxy stateless. Sono accettati due tipi di token.

Tipi di token​

PrefixTypeHow it is obtained
cp_pat_…Personal Access Token (PAT)Created manually in your Copera workspace settings. You paste it into the client config.
cp_oat_…MCP OAuth tokenMinted automatically by the OAuth flow when a client connects without a token.

Personal Access Token (cp_pat_)​

Un PAT è il modo più semplice per connettersi. Lo crei una volta in Copera, gli concedi gli scope e lo incolli nella config del client MCP (vedi Connessione). Il PAT agisce per tuo conto entro gli scope concessi.

I PAT sono ideali per:

  • Client che accettano un header Authorization statico.
  • Setup personali/locali in cui controlli il file di config.
  • Scripting e test con l'MCP Inspector.

Per il modello completo di PAT, scope e ciclo di vita, vedi la guida Autenticazione API.

MCP OAuth (cp_oat_)​

I client compatibili con OAuth (come i remote connector di Claude) possono autenticarsi senza un token incollato. Quando il client chiama per la prima volta il server senza un bearer valido, il server restituisce un 401 con una challenge di discovery e il client percorre il flusso OAuth per ottenere un token cp_oat_… a breve durata. L'utente approva gli scope richiesti in una schermata di consenso Copera e il client memorizza e rinnova il token in modo trasparente.

OAuth è ideale per:

  • Utenti finali che non dovrebbero gestire token grezzi.
  • Client con supporto first-class ai remote connector.
  • Concedere solo gli scope a cui un utente acconsente, per connessione.

Il flusso OAuth​

Il server implementa la spec di autorizzazione MCP sopra i metadata di OAuth 2.0 protected-resource.

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.

Metadata protected-resource​

Il server pubblica i metadata OAuth 2.0 protected-resource su due path well-known:

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

Il documento annuncia la resource, l'authorization server e gli scope supportati:

{
  "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"]
}

La challenge WWW-Authenticate​

Un POST /mcp non autenticato restituisce 401 con una challenge conforme alla spec così i client MCP possono avviare il flusso automaticamente:

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"
I token OAuth vengono introspected a ogni chiamata

Per i token cp_oat_…, il server valida il token contro l'endpoint di introspection dell'API prima di fare proxy. Un token OAuth inattivo o revocato viene rifiutato con 401. I PAT (cp_pat_…) sono validati a valle dalla Public API stessa.

Scope e mappatura ai tool​

Copera MCP Cloud supporta cinque scope OAuth. Ogni scope sblocca una famiglia di tool; un token senza lo scope richiesto ottiene un 403 quando chiama un tool di quella famiglia.

ScopeUnlocksTools
access_boardsBoards, tables, rows, comments, 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_channelsChat channels and direct messageslist_channels, send_message
access_notificationsNotificationslist_notifications, update_notification, delete_notification
access_driveDrive files and foldersget_drive_tree, search_drive, get_drive_item, get_drive_download_url, create_drive_folder
Tool workspace e search

get_workspace_info, list_workspace_members, list_workspace_teams e il tool cross-entity search sono a livello workspace e restituiscono solo ciò che il token è autorizzato a vedere — search filtra i risultati in base alle autorizzazioni del token.

Un 403 di solito indica uno scope mancante

Se un tool restituisce 403 Forbidden, il token molto probabilmente non ha lo scope richiesto. Concedi lo scope sul PAT, oppure rifai il consenso della connessione OAuth con lo scope aggiuntivo.

Alcuni tool — documenti e drive in particolare — sono solo PAT a livello Public API: le integration key non possono raggiungerli. In caso di dubbio, usa un Personal Access Token con gli scope necessari.

Vedi anche​