Pular para o conteúdo principal

Autenticação MCP

Toda requisição ao servidor MCP da Copera carrega um token bearer no header Authorization:

Authorization: Bearer <token>

O servidor MCP encaminha o token para a Copera Public API, que o valida. O servidor em si não armazena credenciais — ele é um proxy sem estado. Dois tipos de token são aceitos.

Tipos de token​

PrefixoTipoComo é obtido
cp_pat_…Personal Access Token (PAT)Criado manualmente nas configurações do seu workspace Copera. Você o cola na configuração do cliente.
cp_oat_…Token OAuth do MCPGerado automaticamente pelo fluxo OAuth quando um cliente conecta sem um token.

Personal Access Tokens (cp_pat_)​

Um PAT é a forma mais simples de conectar. Você o cria uma vez na Copera, concede a ele escopos e o cola na configuração do seu cliente MCP (veja Conectar). O PAT age em seu nome dentro dos escopos que você concedeu.

PATs são ideais para:

  • Clientes que recebem um header Authorization estático.
  • Configurações pessoais/locais onde você controla o arquivo de configuração.
  • Scripts e testes com o MCP Inspector.

Para o modelo completo de PAT, escopos e ciclo de vida, veja o guia de autenticação da API.

MCP OAuth (cp_oat_)​

Clientes com suporte a OAuth (como os conectores remotos do Claude) podem autenticar sem um token colado. Quando o cliente chama o servidor pela primeira vez sem um bearer válido, o servidor retorna um 401 carregando um desafio de descoberta, e o cliente percorre o fluxo OAuth para obter um token cp_oat_… de curta duração. O usuário aprova os escopos solicitados em uma tela de consentimento da Copera, e o cliente armazena e renova o token de forma transparente.

OAuth é ideal para:

  • Usuários finais que não devem manipular tokens brutos.
  • Clientes com suporte de primeira classe a conectores remotos.
  • Conceder apenas os escopos que um usuário consente, por conexão.

O fluxo OAuth​

O servidor implementa a especificação de autorização do MCP sobre os metadados de recurso protegido do 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.

Metadados de recurso protegido​

O servidor publica os metadados de recurso protegido do OAuth 2.0 em dois caminhos bem conhecidos:

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

O documento anuncia o recurso, o servidor de autorização e os escopos suportados:

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

O desafio WWW-Authenticate​

Um POST /mcp não autenticado retorna 401 com um desafio compatível com a especificação para que os clientes MCP possam iniciar o fluxo 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"
Tokens OAuth são introspecionados a cada chamada

Para tokens cp_oat_…, o servidor valida o token contra o endpoint de introspecção da API antes de fazer o proxy. Um token OAuth inativo ou revogado é rejeitado com um 401. PATs (cp_pat_…) são validados a jusante pela própria Public API.

Escopos e como eles mapeiam para ferramentas​

O servidor MCP suporta cinco escopos OAuth. Cada escopo desbloqueia uma família de ferramentas; um token sem o escopo exigido recebe um 403 ao chamar uma ferramenta dessa família.

EscopoDesbloqueiaFerramentas
access_boardsBoards, tabelas, linhas, comentários, exportaçõeslist_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_docsDocumentossearch_docs, get_docs_tree, get_doc, get_doc_content, create_doc, set_doc_content, update_doc_metadata, delete_doc
access_channelsChannels de chat e mensagens diretaslist_channels, send_message
access_notificationsNotificaçõeslist_notifications, update_notification, delete_notification
access_driveArquivos e pastas do driveget_drive_tree, search_drive, get_drive_item, get_drive_download_url, create_drive_folder
Ferramentas de workspace e busca

get_workspace_info, list_workspace_members, list_workspace_teams e a ferramenta de busca entre entidades search são no nível do workspace e retornam apenas o que o token tem permissão de ver — search filtra os resultados pelas permissões do token.

Um 403 geralmente significa um escopo faltando

Se uma ferramenta retornar 403 Forbidden, o token muito provavelmente não tem o escopo exigido. Conceda o escopo no PAT, ou consinta novamente a conexão OAuth com o escopo adicional.

Algumas ferramentas — documentos e drive em particular — são exclusivas de PAT no nível da Public API: integration keys não conseguem alcançá-las. Na dúvida, use um Personal Access Token com os escopos necessários.

Veja também​