Use os Designs da Copera com Seu Agente de Código

Desenhe um app, um dashboard ou um conjunto de páginas como um artefato na Copera e depois entregue-o ao seu agente de código para construir de verdade. Claude Code, Codex, OpenCode e Cursor se conectam ao Copera MCP Cloud e leem tudo o que precisam com uma única chamada de ferramenta: get_artifact_handoff.

O que seu agente recebe

get_artifact_handoff retorna o artefato inteiro em uma leitura:

Parte	O que contém
Spec	A Spec do artefato — para que ele serve, quem o usa e como deve se comportar.
Notas	As notas que as pessoas fixaram nas páginas ou na Spec.
Design	O design compartilhado: arquivos de diretrizes, tokens e componentes, além de logos, fontes e imagens com links de download de curta duração.
Páginas	Cada página com sua superfície, tamanho de viewport, arquivo de entrada e os arquivos que ela carrega.
Links	Como as páginas se ligam umas às outras (os fluxos entre as telas).
Arquivos de código	O código do artefato, com o conteúdo dos arquivos incluído.

Configure

Crie um token com acesso ao Drive

Agentes de código que rodam no seu computador se conectam com um Personal Access Token. Na Copera, abra Workspace Settings → Integrations, crie um Personal Access Token e dê a ele acesso ao Drive (o escopo access_drive). Copie o token (cp_pat_…) — trate-o como uma senha. Veja Autenticação para mais detalhes.

Adicione a Copera ao seu agente de código

Substitua <YOUR_TOKEN> pelo seu token. São as mesmas linhas que a Copera mostra no menu Exportar → Construa com seu agente de código de um artefato.

Claude Code

Execute no terminal:

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

Codex

Adicione ao ~/.codex/config.toml:

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

Depois deixe o token disponível para o Codex:

export COPERA_TOKEN="<YOUR_TOKEN>"

OpenCode

Salve como opencode.json no seu projeto. Se o arquivo já existir, adicione a entrada copera dentro do objeto mcp dele:

opencode.json

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

Cursor

Salve como .cursor/mcp.json no seu projeto. Se o arquivo já existir, adicione a entrada copera dentro do objeto mcpServers dele:

.cursor/mcp.json

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

Reinicie ou recarregue o agente para que ele carregue o servidor copera.

Peça ao seu agente para construir

Copie o pedido no mesmo menu Exportar e envie ao seu agente:

Construa o artefato <nome do artefato> da Copera

Acrescente o que quiser sobre a sua stack, por exemplo "como um app Next.js com Tailwind". O agente encontra o artefato com list_artifacts, chama get_artifact_handoff e constrói a partir do resultado.

Como o agente constrói

get_artifact_handoff diz ao agente o que fazer a seguir, nesta ordem:

1. Ler a Spec — a intenção, as pessoas que usam e as regras.
2. Ler as notas — feedback e decisões fixados nas páginas.
3. Configurar o design — tokens, componentes, fontes, logos e imagens primeiro, para que todas as páginas os compartilhem.
4. Construir cada página a partir dos seus arquivos, na sua superfície e tamanho de viewport.
5. Conectar os links entre as páginas para que os fluxos funcionem.

Por padrão, o agente recebe a versão mais recente do artefato que foi construída com sucesso. Para construir uma versão específica, passe o versionId dela (encontre-o com list_artifact_versions).

Artefatos grandes

Para manter os resultados das ferramentas pequenos, o conteúdo dos arquivos vem incluído até 32 KiB por padrão. Arquivos maiores voltam marcados com omitted: "over_budget", e o agente os lê com read_artifact_source. Se o seu cliente aceitar resultados grandes, o agente pode aumentar maxInlineBytes (até 1 MiB).

Mantenha seu token fora do controle de versão

opencode.json e .cursor/mcp.json costumam ficar dentro de um projeto. Se você colar seu token ali, não faça commit do arquivo. Revogue e recrie o token em Workspace Settings → Integrations se ele vazar.

Solução de problemas

Sintoma	Causa provável
401 Unauthorized	O token está ausente, digitado errado ou expirado. Confira o valor Authorization: Bearer ….
403 Forbidden em uma ferramenta de artefato	O token não tem acesso ao Drive (access_drive), ou Artefatos não estão disponíveis no seu workspace.
O artefato não é encontrado	O usuário do token não pode abrir esse artefato. Peça ao dono para compartilhá-lo com você.
O agente pede para você fazer login	Ele está tentando conectar sem o seu token. Confira de novo a linha de configuração do passo 2.

Relacionados

• Referência de ferramentas — Artefatos — cada ferramenta de artefato e suas entradas.
• Conectar um cliente MCP — detalhes do endpoint e testes com o MCP Inspector.
• Artefatos no Drive — crie, envie e compartilhe artefatos na Copera.