Conectar un cliente MCP

El servidor MCP de Copera es accesible en un único endpoint Streamable HTTP. Apunta tu cliente de IA hacia él, proporciona un bearer token y el catálogo de herramientas aparece automáticamente.

Endpoint

MCP endpoint	https://mcp.copera.ai/mcp
Transport	Streamable HTTP (POST)
Auth header	Authorization: Bearer cp_pat_… or cp_oat_…

Transporte sin estado

El servidor funciona en modo sin estado — no hay sesiones que reanudar. Solo se admite POST /mcp; GET y DELETE devuelven 405. Hay un health check disponible en GET /health.

Necesitarás un token antes de conectarte. La opción más simple es un Personal Access Token (cp_pat_…) creado en la configuración de tu workspace de Copera. Consulta Autenticación para PATs vs. OAuth y cómo los scopes mapean a las herramientas.

Conectar un cliente

Crear un token

Genera un Personal Access Token (cp_pat_…) en tu workspace de Copera y otórgale los scopes que tu agente necesite — por ejemplo access_boards y access_docs. Trátalo como una contraseña.

Agregar el servidor a tu cliente MCP

Configura tu cliente con la URL del endpoint y el bearer token. La mayoría de los clientes aceptan un bloque de configuración de servidor remoto o un comando puente mcp-remote.

Servidor remoto (JSON)

{
  "mcpServers": {
    "copera": {
      "type": "http",
      "url": "https://mcp.copera.ai/mcp",
      "headers": {
        "Authorization": "Bearer cp_pat_YOUR_TOKEN_HERE"
      }
    }
  }
}

Puente mcp-remote

Para clientes que solo admiten servidores stdio locales, haz de puente al endpoint remoto con mcp-remote:

{
  "mcpServers": {
    "copera": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.copera.ai/mcp",
        "--header",
        "Authorization: Bearer cp_pat_YOUR_TOKEN_HERE"
      ]
    }
  }
}

Recargar y verificar que las herramientas aparezcan

Reinicia o recarga el cliente MCP. El servidor copera debería conectarse y exponer sus herramientas (list_boards, search, search_docs, etc.). Si el cliente admite el descubrimiento de herramientas, verás el catálogo completo descrito en la Referencia de herramientas.

Hacer tu primera llamada

Pídele al modelo que llame a get_workspace_info — una herramienta de solo lectura que confirma que el token resuelve al workspace correcto. A partir de ahí, list_boards → list_tables → list_rows recorre el flujo de descubrimiento.

Connectors de OAuth

Algunos clientes (como Claude con connectors remotos) pueden conectarse mediante OAuth en lugar de un token pegado. Cuando agregas la URL del servidor sin un bearer, el cliente recibe un 401 con un desafío WWW-Authenticate e inicia el flujo de OAuth automáticamente, generando un token cp_oat_…. Consulta Autenticación.

Probar con el MCP Inspector

El MCP Inspector es la forma más rápida de confirmar la conectividad y explorar las herramientas a mano antes de conectar un agente.

Iniciar el Inspector

npx @modelcontextprotocol/inspector

Configurar la conexión

En la interfaz del Inspector:

• Transport type: Streamable HTTP
• URL: https://mcp.copera.ai/mcp
• Authentication: agrega un header Authorization con el valor Bearer cp_pat_YOUR_TOKEN_HERE

Listar y llamar herramientas

Conéctate, abre la pestaña Tools y deberías ver las 37 herramientas. Llama a get_workspace_info para verificar el token, luego prueba list_boards para confirmar el acceso de lectura.

Mantén los tokens en secreto

Cualquiera que tenga tu bearer token puede actuar como tú dentro de sus scopes. No subas tokens al control de versiones ni los pegues en configuraciones compartidas. Rota un token de inmediato si se filtra.

Solución de problemas

Síntoma	Causa probable
401 Unauthorized	Bearer token ausente, mal formado o expirado. Revisa de nuevo el header Authorization: Bearer ….
403 Forbidden en una herramienta	El token carece del scope que requiere esa herramienta (p. ej. access_docs para las herramientas de documentos). Consulta Autenticación.
405 Method Not Allowed	El cliente envió GET/DELETE a /mcp. El servidor es sin estado — usa POST.
Faltan herramientas en el cliente	El servidor se conectó pero el cliente filtró las herramientas, o el token resuelve a un workspace sin esos datos. Verifica con el Inspector.