Collegare un client MCP

Copera MCP Cloud è raggiungibile a un singolo endpoint Streamable HTTP. Punta il client IA a quell'URL, fornisci un bearer token e il catalogo dei tool compare automaticamente.

Endpoint

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

Transport stateless

Il server gira in modalità stateless — non ci sono sessioni da riprendere. È supportato solo POST /mcp; GET e DELETE restituiscono 405. Un health check è disponibile a GET /health.

Ti servirà un token prima di connetterti. L'opzione più semplice è un Personal Access Token (cp_pat_…) creato nelle impostazioni del workspace Copera. Vedi Autenticazione per PAT vs. OAuth e come gli scope si mappano ai tool.

Collegare un client

Crea un token

Genera un Personal Access Token (cp_pat_…) nel tuo workspace Copera e concedigli gli scope di cui l'agente ha bisogno — ad esempio access_boards e access_docs. Trattalo come una password.

Aggiungi il server al client MCP

Configura il client con l'URL dell'endpoint e il bearer token. La maggior parte dei client accetta un blocco di config remote-server oppure un comando bridge mcp-remote.

Remote server (JSON)

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

mcp-remote bridge

Per i client che supportano solo server stdio locali, fai da bridge verso l'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"
      ]
    }
  }
}

Ricarica e verifica che i tool compaiano

Riavvia o ricarica il client MCP. Il server copera dovrebbe connettersi ed esporre i suoi tool (list_boards, search, search_docs e così via). Se il client supporta la discovery dei tool, vedrai il catalogo completo descritto nel Riferimento tool.

Fai la prima chiamata

Chiedi al modello di chiamare get_workspace_info — un tool in sola lettura che conferma che il token risolve al workspace giusto. Da lì, list_boards → list_tables → list_rows percorre il flusso di discovery.

Connector OAuth

Alcuni client (come Claude con remote connector) possono connettersi via OAuth invece che con un token incollato. Quando aggiungi l'URL del server senza bearer, il client riceve un 401 con challenge WWW-Authenticate e avvia automaticamente il flusso OAuth, emettendo un token cp_oat_…. Vedi Autenticazione.

Test con l'MCP Inspector

L'MCP Inspector è il modo più rapido per confermare la connettività ed esplorare i tool a mano prima di collegare un agente.

Avvia l'Inspector

npx @modelcontextprotocol/inspector

Configura la connessione

Nell'UI dell'Inspector:

• Transport type: Streamable HTTP
• URL: https://mcp.copera.ai/mcp
• Authentication: aggiungi un header Authorization con il valore Bearer cp_pat_YOUR_TOKEN_HERE

Elenca e chiama i tool

Connettiti, apri la tab Tools e dovresti vedere tutti i 37 tool. Chiama get_workspace_info per verificare il token, poi prova list_boards per confermare l'accesso in lettura.

Tieni i token segreti

Chiunque abbia il tuo bearer token può agire come te entro i suoi scope. Non committare i token nel source control né incollarli in config condivise. Ruota immediatamente un token se viene esposto.

Risoluzione dei problemi

Symptom	Likely cause
401 Unauthorized	Missing, malformed, or expired bearer token. Re-check the Authorization: Bearer … header.
403 Forbidden on a tool	The token lacks the scope that tool requires (e.g. access_docs for document tools). See Authentication.
405 Method Not Allowed	The client sent GET/DELETE to /mcp. The server is stateless — use POST.
Tools missing in the client	The server connected but the client filtered tools, or the token resolves to a workspace without that data. Verify with the Inspector.