Zum Hauptinhalt springen

MCP-Authentifizierung

Jede Anfrage an Copera MCP Cloud trägt ein Bearer-Token im Header Authorization:

Authorization: Bearer <token>

Copera MCP Cloud leitet das Token an die Copera Public API weiter, die es validiert. Der Server speichert selbst keine Credentials — er ist ein zustandsloser Proxy. Zwei Token-Typen werden akzeptiert.

Token-Typen​

PräfixTypWie er beschafft wird
cp_pat_…Personal Access Token (PAT)Manuell in den Workspace-Einstellungen von Copera erstellt. Sie fügen es in die Client-Config ein.
cp_oat_…MCP-OAuth-TokenAutomatisch vom OAuth-Flow ausgestellt, wenn ein Client ohne Token verbindet.

Personal Access Tokens (cp_pat_)​

Ein PAT ist der einfachste Verbindungsweg. Sie erstellen es einmal in Copera, vergeben Scopes und fügen es in die Config Ihres MCP-Clients ein (siehe Verbinden). Das PAT handelt in Ihrem Namen innerhalb der vergebenen Scopes.

PATs eignen sich ideal für:

  • Clients, die einen statischen Header Authorization nehmen.
  • Persönliche/lokale Setups, in denen Sie die Config-Datei kontrollieren.
  • Skripting und Tests mit dem MCP Inspector.

Für das volle PAT-Modell, Scopes und Lebenszyklus siehe den API-Authentifizierungs-Leitfaden.

MCP OAuth (cp_oat_)​

OAuth-fähige Clients (z. B. Claudes Remote-Connectors) können sich ohne eingefügtes Token authentifizieren. Wenn der Client den Server zuerst ohne gültigen Bearer aufruft, liefert der Server ein 401 mit Discovery-Challenge, und der Client durchläuft den OAuth-Flow, um ein kurzlebiges Token cp_oat_… zu erhalten. Der Benutzer genehmigt die angeforderten Scopes in einem Copera-Consent-Screen, und der Client speichert und refreshed das Token transparent.

OAuth eignet sich ideal für:

  • Endbenutzer, die keine Roh-Tokens handhaben sollen.
  • Clients mit First-Class-Remote-Connector-Support.
  • Nur die Scopes gewähren, denen ein Benutzer pro Verbindung zustimmt.

Der OAuth-Flow​

Der Server implementiert die MCP-Authorization-Spec auf Basis von OAuth-2.0-Protected-Resource-Metadata.

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.

Protected-Resource-Metadata​

Der Server veröffentlicht OAuth-2.0-Protected-Resource-Metadata unter zwei well-known-Pfaden:

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

Das Dokument bewirbt die Resource, den Authorization Server und die unterstützten Scopes:

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

Die WWW-Authenticate-Challenge​

Ein unauthentifiziertes POST /mcp liefert 401 mit einer spezifikationskonformen Challenge, damit MCP-Clients den Flow automatisch starten können:

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"
OAuth-Tokens werden bei jedem Aufruf introspektiert

Für Tokens cp_oat_… validiert der Server das Token gegen den Introspection-Endpunkt der API, bevor er proxyt. Ein inaktives oder widerrufenes OAuth-Token wird mit 401 abgelehnt. PATs (cp_pat_…) werden von der Public API selbst downstream validiert.

Scopes und Mapping auf Tools​

Copera MCP Cloud unterstützt fünf OAuth-Scopes. Jeder Scope schaltet eine Tool-Familie frei; einem Token ohne erforderlichen Scope liefert ein Tool-Aufruf in dieser Familie 403.

ScopeSchaltet freiTools
access_boardsBoards, Tabellen, Zeilen, Kommentare, Exportelist_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_docsDokumentesearch_docs, get_docs_tree, get_doc, get_doc_content, create_doc, set_doc_content, update_doc_metadata, delete_doc
access_channelsChat-Channels und Direktnachrichtenlist_channels, send_message
access_notificationsBenachrichtigungenlist_notifications, update_notification, delete_notification
access_driveDrive-Dateien und -Ordnerget_drive_tree, search_drive, get_drive_item, get_drive_download_url, create_drive_folder
Workspace-Tools und Suche

get_workspace_info, list_workspace_members, list_workspace_teams und das Cross-Entity-Tool search sind workspace-weit und liefern nur, was das Token sehen darf — search filtert Ergebnisse nach den Berechtigungen des Tokens.

Ein 403 bedeutet meist einen fehlenden Scope

Wenn ein Tool 403 Forbidden liefert, fehlt dem Token sehr wahrscheinlich der erforderliche Scope. Gewähren Sie den Scope am PAT oder stimmen Sie der OAuth-Verbindung mit dem zusätzlichen Scope erneut zu.

Manche Tools — insbesondere Dokumente und Drive — sind auf Public-API-Ebene nur PAT: Integration Keys erreichen sie nicht. Im Zweifel verwenden Sie ein Personal Access Token mit den benötigten Scopes.

Siehe auch​