Skip to main content

MCP Authentication

Every request to the Copera MCP server carries a bearer token in the Authorization header:

Authorization: Bearer <token>

The MCP server forwards the token to the Copera Public API, which validates it. The server itself does not store credentials — it is a stateless proxy. Two token types are accepted.

Token types​

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 Tokens (cp_pat_)​

A PAT is the simplest way to connect. You create it once in Copera, grant it scopes, and paste it into your MCP client's config (see Connect). The PAT acts on your behalf within the scopes you granted.

PATs are ideal for:

  • Clients that take a static Authorization header.
  • Personal/local setups where you control the config file.
  • Scripting and testing with the MCP Inspector.

For the full PAT model, scopes, and lifecycle, see the API authentication guide.

MCP OAuth (cp_oat_)​

OAuth-capable clients (such as Claude's remote connectors) can authenticate without a pasted token. When the client first calls the server with no valid bearer, the server returns a 401 carrying a discovery challenge, and the client walks the OAuth flow to obtain a short-lived cp_oat_… token. The user approves the requested scopes in a Copera consent screen, and the client stores and refreshes the token transparently.

OAuth is ideal for:

  • End users who should not handle raw tokens.
  • Clients with first-class remote-connector support.
  • Granting only the scopes a user consents to, per connection.

The OAuth flow​

The server implements the MCP authorization spec on top of 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​

The server publishes OAuth 2.0 protected-resource metadata at two well-known paths:

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

The document advertises the resource, the authorization server, and the supported 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"]
}

The WWW-Authenticate challenge​

An unauthenticated POST /mcp returns 401 with a spec-compliant challenge so MCP clients can begin the flow automatically:

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 are introspected on every call

For cp_oat_… tokens, the server validates the token against the API's introspection endpoint before proxying. An inactive or revoked OAuth token is rejected with a 401. PATs (cp_pat_…) are validated downstream by the Public API itself.

Scopes and how they map to tools​

The MCP server supports five OAuth scopes. Each scope unlocks a family of tools; a token missing the required scope gets a 403 when it calls a tool in that family.

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
Workspace tools and search

get_workspace_info, list_workspace_members, list_workspace_teams, and the cross-entity search tool are workspace-level and return only what the token is allowed to see — search filters results by the token's permissions.

A 403 usually means a missing scope

If a tool returns 403 Forbidden, the token most likely lacks the required scope. Grant the scope on the PAT, or re-consent the OAuth connection with the additional scope.

Some tools — documents and drive in particular — are PAT-only at the Public API level: integration keys cannot reach them. When in doubt, use a Personal Access Token with the needed scopes.

See also​