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_agenda access_agents access_automations access_boards access_bookings access_channels access_contacts access_designs access_docs access_drive access_meeting_notes access_notifications access_time"
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_agenda",
"access_agents",
"access_automations",
"access_boards",
"access_bookings",
"access_canvas",
"access_channels",
"access_contacts",
"access_designs",
"access_docs",
"access_drive",
"access_meeting_notes",
"access_notifications",
"access_time"
],
"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_agenda access_agents access_automations access_boards access_bookings access_channels access_contacts access_designs access_docs access_drive access_meeting_notes access_notifications access_time"
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 gli scope OAuth elencati di seguito. 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_driveFile e cartelle di Drive, strumenti di design esistentiget_drive_tree, search_drive, get_drive_item, get_drive_download_url, create_drive_folder, import_artifact_asset, get_artifact_handoff, list_artifacts, …
access_designsDesignget_artifact_handoff, list_artifacts, push_artifact_version, get_artifact_build, check_artifact, get_artifact_guide, rename_artifact, trash_artifact, restore_artifact_version, fork_artifact, get_artifact_archive_link
access_canvasLeggere e modificare le lavagne Canvascanvas_list, canvas_create, canvas_read, canvas_edit, canvas_undo, canvas_look

Per accedere alle lavagne, seleziona Canvas quando crei un PAT. Il client OAuth deve registrare e richiedere access_canvas e l’utente deve approvare la nuova autorizzazione.

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​