Usa i design di Copera con il tuo agente di programmazione

Progetta un'app, una dashboard o un insieme di pagine come artefatto in Copera, poi affidalo al tuo agente di programmazione per costruirlo davvero. Claude Code, Codex, OpenCode e Cursor si collegano a Copera MCP Cloud e leggono tutto ciò che serve con una sola chiamata a un tool: get_artifact_handoff.

Cosa riceve il tuo agente

get_artifact_handoff restituisce l'intero artefatto in una sola lettura:

Parte	Contenuto
Spec	La Spec dell'artefatto — a cosa serve, chi lo usa e come deve comportarsi.
Note	Le note fissate alle pagine o alla Spec.
Design	Il design condiviso: file di linee guida, token e componenti, più loghi, font e immagini con link di download a breve scadenza.
Pagine	Ogni pagina con la sua superficie, dimensione del viewport, file di ingresso e i file che carica.
Link	Come le pagine si collegano tra loro (i flussi tra le schermate).
File sorgente	Il codice dell'artefatto, con il contenuto dei file incluso.

Configurazione

Crea un token con accesso a Drive

Gli agenti di programmazione che girano sul tuo computer si collegano con un Personal Access Token. In Copera, apri Workspace Settings → Integrations, crea un Personal Access Token e dagli accesso a Drive (lo scope access_drive). Copia il token (cp_pat_…) — trattalo come una password. Vedi Autenticazione per i dettagli.

Aggiungi Copera al tuo agente di programmazione

Sostituisci <YOUR_TOKEN> con il tuo token. Sono le stesse righe che Copera mostra nel menu Esporta → Costruiscilo con il tuo agente di codice di un artefatto.

Claude Code

Esegui nel terminale:

claude mcp add --transport http copera https://mcp.copera.ai/mcp --header "Authorization: Bearer <YOUR_TOKEN>"

Codex

Aggiungi a ~/.codex/config.toml:

[mcp_servers.copera]
url = "https://mcp.copera.ai/mcp"
bearer_token_env_var = "COPERA_TOKEN"

Poi rendi il token disponibile a Codex:

export COPERA_TOKEN="<YOUR_TOKEN>"

OpenCode

Salvalo come opencode.json nel tuo progetto. Se il file esiste già, aggiungi invece la voce copera dentro il suo oggetto mcp:

opencode.json

{
  "mcp": {
    "copera": {
      "type": "remote",
      "url": "https://mcp.copera.ai/mcp",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}

Cursor

Salvalo come .cursor/mcp.json nel tuo progetto. Se il file esiste già, aggiungi invece la voce copera dentro il suo oggetto mcpServers:

.cursor/mcp.json

{
  "mcpServers": {
    "copera": {
      "url": "https://mcp.copera.ai/mcp",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}

Riavvia o ricarica l'agente perché carichi il server copera.

Chiedi al tuo agente di costruirlo

Copia la richiesta dallo stesso menu Esporta e inviala al tuo agente:

Costruisci l’artefatto <nome dell'artefatto> da Copera

Aggiungi ciò che vuoi sul tuo stack, per esempio "come app Next.js con Tailwind". L'agente trova l'artefatto con list_artifacts, chiama get_artifact_handoff e costruisce dal risultato.

Come costruisce l'agente

get_artifact_handoff dice all'agente cosa fare dopo, in quest'ordine:

1. Leggere la Spec — l'intento, le persone che lo usano e le regole.
2. Leggere le note — feedback e decisioni fissati alle pagine.
3. Impostare il design — prima token, componenti, font, loghi e immagini, così tutte le pagine li condividono.
4. Costruire ogni pagina dai suoi file, con la sua superficie e dimensione del viewport.
5. Collegare i link tra le pagine perché i flussi funzionino.

Per impostazione predefinita, l'agente riceve l'ultima versione dell'artefatto costruita con successo. Per costruire una versione precisa, passa il suo versionId (lo trovi con list_artifact_versions).

Artefatti grandi

Per mantenere piccoli i risultati dei tool, il contenuto dei file è incluso fino a 32 KiB di default. I file più grandi tornano contrassegnati omitted: "over_budget" e l'agente li legge con read_artifact_source. Se il tuo client accetta risultati grandi, l'agente può aumentare maxInlineBytes (fino a 1 MiB).

Tieni il token fuori dal controllo di versione

opencode.json e .cursor/mcp.json spesso stanno dentro un progetto. Se ci incolli il tuo token, non fare commit del file. Revoca il token e creane uno nuovo in Workspace Settings → Integrations se dovesse trapelare.

Risoluzione dei problemi

Sintomo	Causa probabile
401 Unauthorized	Il token manca, è scritto male o è scaduto. Controlla il valore Authorization: Bearer ….
403 Forbidden su un tool degli artefatti	Il token non ha accesso a Drive (access_drive), oppure gli Artefatti non sono disponibili nel tuo workspace.
L'artefatto non viene trovato	L'utente del token non può aprire quell'artefatto. Chiedi al proprietario di condividerlo con te.
L'agente ti chiede di accedere	Sta provando a collegarsi senza il tuo token. Ricontrolla la riga di configurazione del passo 2.

Correlati

• Riferimento dei tool — Artefatti — ogni tool degli artefatti e i suoi input.
• Collegare un client MCP — dettagli dell'endpoint e test con il MCP Inspector.
• Artefatti in Drive — crea, carica e condividi artefatti in Copera.