Pular para o conteúdo principal

Casos de Uso do MCP

Estes workflows mostram como um agente de IA encadeia ferramentas MCP da Copera para realizar trabalho de verdade. Como o servidor é sem estado, toda ferramenta de board/tabela/linha precisa de ObjectIds hex explícitos — então a maioria dos fluxos começa com descoberta (list_boards → list_tables → get_table_schema) antes de ler ou escrever.

Cada exemplo mostra as chamadas de ferramentas em ordem, com os argumentos principais. Os resultados das ferramentas são JSON; o agente lê ids e valores de um resultado para alimentar a próxima chamada.

Encontrar um board e ler suas linhas​

O padrão mais comum: localizar um board por nome, encontrar uma tabela e então ler as linhas.

Encontre o board
list_boards({ query: "Roadmap" })
// → [{ id: "66ab…b01", name: "Q3 Roadmap", … }]
Encontre a tabela
list_tables({ boardId: "66ab…b01", query: "Features" })
// → [{ id: "66ab…t02", name: "Features", columns: [...] }]
Leia o schema, depois as linhas
get_table_schema({ boardId: "66ab…b01", tableId: "66ab…t02" })
// → column ids + STATUS/DROPDOWN option ids

list_rows({ boardId: "66ab…b01", tableId: "66ab…t02", sort: "66ab…date:desc" })
// → rows with cell values keyed by columnId
Filtre em vez de varrer

list_rows não é paginado e pode ser grande. Restrinja com query, um filter estruturado ({ match, conditions: [{ column_id, operator, value }] }) e sort em vez de ler cada linha.

Atualizar o status de uma linha​

Ler o schema primeiro é obrigatório para que você use o columnId real e um id de opção válido.

get_table_schema({ boardId, tableId })
// find the STATUS column id and the "Done" option id

update_row({
  boardId,
  tableId,
  rowId: "66ab…r07",
  columns: [{ columnId: "66ab…status", value: "66ab…doneOption" }],
})

Para editar a descrição de texto longo de uma linha ou uma célula de coluna RICH TEXT, use set_row_markdown em vez disso — update_row não mexe em texto longo. Escritas em markdown são enfileiradas (HTTP 202), então releia com get_row_markdown para confirmar.

Buscar docs e resumir​

Puxe o documento mais relevante para uma palavra-chave, busque seu corpo e deixe o modelo resumi-lo.

Busca
search_docs({ query: "onboarding checklist", limit: 5 })
// → ranked hits with highlights showing what matched
Leia o conteúdo do hit principal
get_doc_content({ docId: "66ab…d11" })
// → full markdown body (can be large — only fetch when you need it)
Resumir

O agente resume o markdown retornado em sua própria resposta. Para navegar em vez de buscar, use get_docs_tree para percorrer a hierarquia.

Capturar um resumo de volta em um novo doc​

Combine leitura com escrita — pesquise pelo workspace, depois persista o resultado.

search({ query: "Q3 launch", types: ["document", "channelMessage"], limit: 20 })
// gather context across docs and chat

create_doc({ title: "Q3 Launch Summary", content: "# Summary\n\n…" })
// → { id: "66ab…d99" }

// append more later (async — re-read to confirm)
set_doc_content({ docId: "66ab…d99", content: "\n\n## Risks\n…", operation: "append" })

Postar uma mensagem em um channel​

Notifique um channel, ou mande mensagem direta a uma pessoa específica. Forneça exatamente um de channelId ou userId.

Encontre o channel (ou o usuário)
list_channels({ query: "engineering", type: "text" })
// → [{ id: "66ab…c01", name: "engineering" }]

// or resolve a DM target:
list_workspace_members({ query: "alex@" })
// → [{ id: "66ab…u22", name: "Alex", email: "alex@…" }]
Enviar
// post to a channel (synchronous)
send_message({ channelId: "66ab…c01", message: "Deploy is green ✅" })

// or direct-message a user (queued, may not appear immediately)
send_message({ userId: "66ab…u22", message: "Can you review the PR?" })
Sobreposição do nome do remetente

O name opcional (sobreposição do nome de exibição) é exclusivo de channel — é rejeitado ao enviar uma mensagem direta.

Triar notificações​

Leia a caixa de entrada, marque itens como tratados e limpe o ruído.

list_notifications()
// → { notifications: [...], unreadCount, count }

update_notification({ notificationId: "66ab…n05", status: "read" })

delete_notification({ notificationId: "66ab…n06" }) // no undo

A paginação usa ObjectIds de notificação como cursores: passe o id mais antigo retornado como after para voltar pelo histórico.

Comentar em uma linha para um cliente​

Adicione um comentário visível externamente a uma linha de board — use external deliberadamente, apenas quando pessoas fora do workspace devem vê-lo.

list_row_comments({ boardId, tableId, rowId, visibility: "all" })
// review the thread (cursor-paginated via pageInfo.endCursor)

add_row_comment({
  boardId,
  tableId,
  rowId,
  content: "We shipped the fix in today's release.",
  visibility: "external",
})

Exportar uma view e salvá-la no drive​

Renderize uma view de tabela para um arquivo. Para PDF/ZIP ou exportações grandes, prefira saveToDrive: true para que o arquivo caia no drive em vez de um payload inline.

// viewId comes from list_tables / get_table_schema
export_table({
  boardId,
  tableId,
  viewId: "66ab…v01",
  format: "PDF",
  saveToDrive: true,
})
// → async job snapshot + a drive reference

// later, fetch the file
get_drive_download_url({ fileId: "66ab…f44" })
// → presigned CloudFront url (fetch directly, no auth)

Dicas para execuções de agentes confiáveis​

  • Descubra antes de escrever. Chame get_table_schema para obter columnIds reais e ids de opções antes de create_row / update_row / set_row_markdown — tipos de coluna não suportados em create_row são silenciosamente ignorados.
  • Releia após escritas assíncronas. set_row_markdown, set_doc_content e mensagens diretas são eventualmente consistentes.
  • Mantenha o volume de requisições razoável. A API limita a taxa; 429s são repetidos automaticamente com backoff, mas agentes que se espalham ainda podem atingir os limites. Restrinja buscas e listas com query/filter/limit.
  • Atente aos escopos. Um 403 quase sempre significa que o token está sem um escopo para aquela ferramenta — veja Autenticação.

Veja também​