Skip to main content

MCP Tool Reference

This page lists 52 Copera MCP Cloud tools across ten domains. Each tool is a thin wrapper over a Copera Public API endpoint — the Public API capability column shows the underlying endpoint each tool calls.

DomainTools
Workspace3
Board11
Search1
Docs8
Notifications3
Chat2
Comment3
Drive5
Export1
Design Artifacts15
Total52
Discovery is explicit

The server is stateless, so board/table/row tools need explicit hex ObjectIds. The discovery flow is get_workspace_info → list_boards → list_tables → get_table_schema → list_rows. Always call get_table_schema before writing rows so you use real columnIds and valid option IDs.

Workspace​

Scope: workspace-level (results filtered by token permissions).

ToolDescriptionPublic API capability
get_workspace_infoBasic metadata about the workspace the token belongs to (name, slug, seat count, timestamps).GET /workspace/info
list_workspace_membersList members to resolve a user id from a name or email; offset-paginated, optional query.GET /workspace/members
list_workspace_teamsList teams with their participant user ids; offset-paginated, optional query.GET /workspace/teams

Board​

Scope: access_boards. The discovery → query → write loop over boards, tables, and rows.

ToolDescriptionPublic API capability
list_boardsList boards the token can access, optional name search. Start here to find a boardId.GET /board/list-boards
get_boardMetadata for a single board by boardId.GET /board/{boardId}
list_tablesList a board's tables with column definitions, optional name search.GET /board/{boardId}/tables
get_table_schemaFull column definitions for a table, including option IDs for STATUS/DROPDOWN/LABELS columns.GET /board/{boardId}/table/{tableId}
list_rowsList rows in a table with optional query, structured filter, and sort. Not paginated.GET /board/{boardId}/table/{tableId}/rows
get_rowGet one row by hex rowId or by visible rowNumber (provide exactly one).GET …/row/{rowId} or GET …/row-number/{rowNumber}
create_rowCreate a row from { columnId, value } cells; optional legacy description.POST /board/{boardId}/table/{tableId}/row
update_rowUpdate cell values of an existing row by rowId (does not edit long text).PATCH …/row/{rowId}
delete_rowMove a row to the board trash for up to 30 days. Returns a trashBatchId for restore.DELETE …/row/{rowId}
list_row_trashList deleted rows you can access, with optional table, search, and paging filters.GET /board/{boardId}/trash/rows
restore_rowsRestore rows by delete batch ID or by trash entry IDs.POST /board/{boardId}/trash/rows/restore
get_row_markdownRead long-text markdown: the legacy row description, or a RICH TEXT column cell if columnId is given.GET …/row/{rowId}/md or …/column/{columnId}/md
set_row_markdownWrite markdown (replace/append/prepend) to the legacy description or a RICH TEXT column cell. Async (HTTP 202).POST …/row/{rowId}/md or …/column/{columnId}/md

Scope: workspace-level (results filtered by token permissions).

ToolDescriptionPublic API capability
searchCross-entity full-text search over documents, channels, messages, todos, drive files, voice transcriptions, and AI chats. Restrict with types.GET /search/

Docs​

Scope: access_docs (documents are PAT-only).

ToolDescriptionPublic API capability
search_docsFull-text search across documents with ranked hits and highlights.GET /docs/search
get_docs_treeBrowse the document hierarchy; omit parentId for root, bound with depth.GET /docs/tree
get_docDocument metadata (title, icon, cover, owner, parent, timestamps) by docId.GET /docs/{docId}
get_doc_contentFull markdown body of a document by docId (can be large).GET /docs/{docId}/md
create_docCreate a document with a title, optional parentId and seed content.POST /docs/
set_doc_contentWrite markdown (replace/append/prepend) to a document body. Requires edit access (admin/member, including team shares); 403 if the caller can see the doc but cannot edit it. Async (HTTP 202).POST /docs/{docId}/md
update_doc_metadataUpdate a document's title, icon, and/or cover (not the body).PATCH /docs/{docId}
delete_docDelete a document by docId (owner only). No undo.DELETE /docs/{docId}

Notifications​

Scope: access_notifications (for the token's own user).

ToolDescriptionPublic API capability
list_notificationsList the token user's notifications with unreadCount; id-cursor paginated (after/before).GET /notifications/
update_notificationMark one notification read or unread by notificationId.PATCH /notifications/{notificationId}
delete_notificationDelete one notification by notificationId. No undo.DELETE /notifications/{notificationId}

Chat​

Scope: access_channels.

ToolDescriptionPublic API capability
list_channelsList channels and DM conversations; filter by query/type/kind/participantId; offset-paginated.GET /chat/channels
send_messageSend a message to a channel (channelId) or direct-message a user (userId) — exactly one.POST /chat/channel/{channelId}/send-message or POST /chat/direct-message/send-message

Comment​

Scope: access_boards. Row comments and attachment references.

ToolDescriptionPublic API capability
list_row_commentsList row comments, newest first, with author and attachment metadata, file references, anchors, and resolved state. Supports cursor pagination and fileId and visibility filters.GET …/row/{rowId}/comments
add_row_commentAdd a comment to a row or FILE attachment, with an optional image pin or audio/video time. visibility defaults to internal.POST …/row/{rowId}/comment
resolve_row_commentMark a file comment done or reopen it.POST …/row/{rowId}/comment/{commentId}/resolve
update_row_fileRename or describe a FILE-column attachment.PATCH …/row/{rowId}/column/{columnId}/file/{fileId}
get_row_attachment_urlResolve an authenticated downloadUrl for a FILE-column or comment attachment (no bytes returned).…/column/{columnId}/file/{fileId}/download or …/comment/{commentId}/file/{fileId}/download

Drive​

Scope: access_drive (drive is PAT-only).

ToolDescriptionPublic API capability
get_drive_treeBrowse the drive as a nested file/folder tree; depth-bounded, with truncation drill-down.GET /drive/tree
search_driveFull-text search across drive files and folders.GET /drive/search
get_drive_itemMetadata for a single file or folder by fileId.GET /drive/files/{fileId}
get_drive_download_urlTime-limited presigned CloudFront download URL for a file (no auth needed to fetch).GET /drive/files/{fileId}/download
create_drive_folderCreate a folder at root or under a parentId.POST /drive/folders

Export​

Scope: access_boards.

ToolDescriptionPublic API capability
export_tableRender a table view to CSV/XLSX/JSON/MARKDOWN/HTML/PDF/ZIP/ICS; inline or queued; saveToDrive for large/binary.POST /board/{boardId}/table/{tableId}/export

Design Artifacts​

Scope: access_drive, and your workspace must have Design Artifacts available. Read and edit the apps, dashboards, and pages people build in Copera — and hand them to a coding agent.

ToolDescriptionPublic API capability
get_artifact_handoffThe one call to build from a Design. Returns the Design link, the version, the Spec, the notes, the shared design (guidance, tokens, components, and assets with short-lived download links), every page (surface, viewport, entry file, and the files it loads), the links between pages, and the source files. For a design built on shadcn/ui it also returns a shadcn block — preset, shadcn CLI commands (a non-interactive new-project command and an existing-project command), globals.css, and each page's suggested route and components — and leaves out shadcn/ui components nobody changed in Copera (omitted: "shadcn_registry") and the tokens file the block already carries (omitted: "in_shadcn_block"). Optional versionId and maxInlineBytes.GET /artifacts/{artifactId}/handoff
list_artifactsList Designs you can open; scope is mine or shared, optional search, cursor-paginated (after, limit up to 50).GET /artifacts/
get_artifactThe Design's current version: pages, shared design, assets, the file list with SHA-256 digests, and the preview. Read file contents with read_artifact_source.GET /artifacts/{artifactId}
list_artifact_versionsThe Design's version history; cursor-paginated (after, limit up to 50).GET /artifacts/{artifactId}/versions
get_artifact_versionPages, shared design, and file list of one version (versionId). A version never changes once saved.GET …/versions/{versionId}
read_artifact_sourceRead one source file (path) from a version in bounded chunks. Continue with the returned nextCursor until eof is true.GET …/versions/{versionId}/source
get_artifact_page_previewPreview of one page (pageId) of a version.GET …/versions/{versionId}/pages/{pageId}/preview
get_artifact_design_snapshotA reusable copy of a version's shared design (guidance, tokens, components, assets) with its digest — pass it to create_artifact as reuseDesign.GET …/versions/{versionId}/design
list_artifact_design_startersThe design starters create_artifact can seed (designStarterId): the shadcn/ui starter with its default setup, every option a setup accepts (libraries, styles, colors, fonts, icons, radius, menu), and the components available per library. Also returns the paths and sizes (never the contents) of the files, and the pinned packages, of the starter with that default setup.GET /artifacts/starters
list_artifact_design_systemsThe shadcn/ui design systems your workspace saved: id, name, summary, preset code, library, and the full setup. Pass an id to create_artifact as designSystemId.GET /artifacts/design-systems
parse_shadcn_setupCheck a pasted shadcn/ui setup without creating anything — a preset code, an npx shadcn@latest init --preset … command, a ui.shadcn.com link, theme CSS, or a components.json. Returns the setup it understood (spec, summary, presetCode, initCommand), what it recognized, and anything it could not apply (warnings). Optional library (radix, base, or aria) when the text does not say. Needs the workspace's Design Artifacts feature.POST /artifacts/shadcn/parse
list_artifact_assetsLogos, fonts, images, and references added to the Design's shared design.GET /artifacts/{artifactId}/design-assets
import_artifact_assetAdd a file you uploaded (fileId) to the Design's shared design as a logo, font, image, or reference, with optional altText. Place it on a page with patch_artifact_source.POST /artifacts/{artifactId}/design-assets
patch_artifact_sourceEdit source files on top of baseVersionId with replace_text, put_file, and delete_file operations (up to 32 files), each checked against the file's current SHA-256. Queued — poll get_artifact_request.POST /artifacts/{artifactId}/source-patches
list_artifact_requestsRecent edit requests on the Design, with their status and the version each one produced.GET /artifacts/{artifactId}/requests
get_artifact_requestStatus of one edit request (requestId) and the exact version it produced.GET /artifacts/{artifactId}/requests/{requestId}
create_artifactCreate a private Design from your own source project (static_web or vite_react), with a title, a request describing what it is for, and an idempotencyKey. Optionally seed the real shadcn/ui components with designStarterId: "shadcn" (shadcn's default setup), and choose your own setup with one of shadcnSetup (pasted text), shadcn (a setup object), or designSystemId (a saved design system) — or reuse a design with reuseDesign. reuseDesign cannot be combined with the others, and a shadcn/ui design needs a vite_react project. The result includes a shadcn field with the setup that was applied and any warnings.POST /artifacts/
Build from a Design in one call

get_artifact_handoff is all a coding agent needs. Work through the result in order: read the Spec, then the notes, then set up the design, then build each page from its files, then wire the links between pages — and follow the returned nextSteps. Omit versionId to get the latest version that built successfully. File contents are inlined up to maxInlineBytes (32 KiB by default, up to 1 MiB if your client accepts large tool results); files marked omitted: "over_budget" are read with read_artifact_source using the returned version id. See Build with your coding agent for the setup.

For a design built on shadcn/ui, the result has a shadcn block: set your app up with its shadcn CLI commands (newProjectCommand, which names the project and skips the prompts so it runs without a terminal, then cd into projectDirectory, then addCommand) instead of copying component files, make globalsCss the app's src/index.css (shared/tokens.css is that same text and comes back marked omitted: "in_shadcn_block") or, in an app that already has its own stylesheet, merge its blocks into it (existingProjectCommand applies the preset but not the colors listed in customTokens), start every page's entryFile with import "./index.css", then port each page from shared/ to src/ at its suggestedRoute (or, with no router, as its own HTML entry listed with viteInputsSnippet). The pages were built without type-checking, so fix unused imports and type errors while porting. Files marked omitted: "shadcn_registry" are shadcn/ui components nobody changed in Copera, which the CLI writes; files with a note are customized ones (or ones Copera has no record of) to copy over what the CLI wrote.

Behavior notes​

Async writes are eventually consistent

set_row_markdown and set_doc_content are queued (HTTP 202) — re-read with get_row_markdown / get_doc_content to confirm the change landed. Channel sends are synchronous; direct messages are queued and may not appear immediately.

Design edits are queued

patch_artifact_source and create_artifact return a receipt, not a finished build. After a patch, poll get_artifact_request until the request is completed or failed, then read the version it produced; after a create, read the returned Design and its preview. Reuse an idempotencyKey only to retry the identical request. If a file changed since you read it, the edit fails with a conflict — read it again and retry.

Confirm deletion targets

delete_doc and delete_notification permanently remove data. Rows deleted with delete_row can be restored for up to 30 days, unless purged earlier.

No tool ever returns raw file bytes. get_drive_download_url returns a presigned URL you can fetch without auth; get_row_attachment_url returns an authenticated downloadUrl you fetch yourself with your bearer token.

For the request/response schema of each underlying endpoint, see the API Reference.