Autenticación de MCP

Cada petición al servidor MCP de Copera lleva un bearer token en el header Authorization:

Authorization: Bearer <token>

El servidor MCP reenvía el token a la Copera Public API, que lo valida. El servidor en sí no almacena credenciales — es un proxy sin estado. Se aceptan dos tipos de token.

Tipos de token

Prefijo	Tipo	Cómo se obtiene
cp_pat_…	Personal Access Token (PAT)	Creado manualmente en la configuración de tu workspace de Copera. Lo pegas en la configuración del cliente.
cp_oat_…	MCP OAuth token	Generado automáticamente por el flujo de OAuth cuando un cliente se conecta sin token.

Personal Access Tokens (cp_pat_)

Un PAT es la forma más simple de conectarse. Lo creas una vez en Copera, le otorgas scopes y lo pegas en la configuración de tu cliente MCP (consulta Conectar). El PAT actúa en tu nombre dentro de los scopes que otorgaste.

Los PATs son ideales para:

• Clientes que aceptan un header Authorization estático.
• Configuraciones personales/locales donde tú controlas el archivo de configuración.
• Scripting y pruebas con el MCP Inspector.

Para el modelo completo de PAT, scopes y ciclo de vida, consulta la guía de autenticación de la API.

MCP OAuth (cp_oat_)

Los clientes compatibles con OAuth (como los connectors remotos de Claude) pueden autenticarse sin un token pegado. Cuando el cliente llama por primera vez al servidor sin un bearer válido, el servidor devuelve un 401 con un desafío de descubrimiento, y el cliente recorre el flujo de OAuth para obtener un token cp_oat_… de corta duración. El usuario aprueba los scopes solicitados en una pantalla de consentimiento de Copera, y el cliente almacena y refresca el token de forma transparente.

OAuth es ideal para:

• Usuarios finales que no deberían manejar tokens en bruto.
• Clientes con soporte de primera clase para connectors remotos.
• Otorgar solo los scopes que un usuario consiente, por conexión.

El flujo de OAuth

El servidor implementa la especificación de autorización de MCP sobre los metadatos de recurso protegido de 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.

Metadatos de recurso protegido

El servidor publica los metadatos de recurso protegido de OAuth 2.0 en dos rutas well-known:

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

El documento anuncia el recurso, el servidor de autorización y los scopes admitidos:

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

El desafío WWW-Authenticate

Un POST /mcp no autenticado devuelve 401 con un desafío conforme a la especificación para que los clientes MCP puedan iniciar el flujo automáticamente:

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"

Los tokens de OAuth se inspeccionan en cada llamada

Para los tokens cp_oat_…, el servidor valida el token contra el endpoint de introspección de la API antes de hacer de proxy. Un token de OAuth inactivo o revocado se rechaza con un 401. Los PATs (cp_pat_…) son validados aguas abajo por la propia Public API.

Scopes y cómo mapean a las herramientas

El servidor MCP admite cinco scopes de OAuth. Cada scope desbloquea una familia de herramientas; un token que carezca del scope requerido recibe un 403 cuando llama a una herramienta de esa familia.

Scope	Desbloquea	Herramientas
access_boards	Boards, tablas, filas, comentarios, exportaciones	list_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_docs	Documentos	search_docs, get_docs_tree, get_doc, get_doc_content, create_doc, set_doc_content, update_doc_metadata, delete_doc
access_channels	Canales de chat y mensajes directos	list_channels, send_message
access_notifications	Notificaciones	list_notifications, update_notification, delete_notification
access_drive	Archivos y carpetas de Drive	get_drive_tree, search_drive, get_drive_item, get_drive_download_url, create_drive_folder

Herramientas de workspace y búsqueda

get_workspace_info, list_workspace_members, list_workspace_teams y la herramienta de búsqueda entre entidades search operan a nivel de workspace y devuelven solo lo que el token tiene permitido ver — search filtra los resultados según los permisos del token.

Un 403 normalmente significa un scope faltante

Si una herramienta devuelve 403 Forbidden, lo más probable es que el token carezca del scope requerido. Otorga el scope en el PAT, o vuelve a consentir la conexión de OAuth con el scope adicional.

Algunas herramientas — documentos y drive en particular — son solo PAT a nivel de la Public API: las claves de integración no pueden alcanzarlas. En caso de duda, usa un Personal Access Token con los scopes necesarios.

Ver también

• Conectar un cliente MCP — endpoint, configuración y pruebas con el Inspector.
• Referencia de herramientas — cada herramienta y el scope que necesita.
• Guía de autenticación de la API — el modelo de PAT compartido con la REST API.