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.
| Domain | Tools |
|---|---|
| Workspace | 3 |
| Board | 11 |
| Search | 1 |
| Docs | 8 |
| Notifications | 3 |
| Chat | 2 |
| Comment | 3 |
| Drive | 5 |
| Export | 1 |
| Design Artifacts | 15 |
| Total | 52 |
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).
| Tool | Description | Public API capability |
|---|---|---|
get_workspace_info | Basic metadata about the workspace the token belongs to (name, slug, seat count, timestamps). | GET /workspace/info |
list_workspace_members | List members to resolve a user id from a name or email; offset-paginated, optional query. | GET /workspace/members |
list_workspace_teams | List 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.
| Tool | Description | Public API capability |
|---|---|---|
list_boards | List boards the token can access, optional name search. Start here to find a boardId. | GET /board/list-boards |
get_board | Metadata for a single board by boardId. | GET /board/{boardId} |
list_tables | List a board's tables with column definitions, optional name search. | GET /board/{boardId}/tables |
get_table_schema | Full column definitions for a table, including option IDs for STATUS/DROPDOWN/LABELS columns. | GET /board/{boardId}/table/{tableId} |
list_rows | List rows in a table with optional query, structured filter, and sort. Not paginated. | GET /board/{boardId}/table/{tableId}/rows |
get_row | Get one row by hex rowId or by visible rowNumber (provide exactly one). | GET …/row/{rowId} or GET …/row-number/{rowNumber} |
create_row | Create a row from { columnId, value } cells; optional legacy description. | POST /board/{boardId}/table/{tableId}/row |
update_row | Update cell values of an existing row by rowId (does not edit long text). | PATCH …/row/{rowId} |
delete_row | Move a row to the board trash for up to 30 days. Returns a trashBatchId for restore. | DELETE …/row/{rowId} |
list_row_trash | List deleted rows you can access, with optional table, search, and paging filters. | GET /board/{boardId}/trash/rows |
restore_rows | Restore rows by delete batch ID or by trash entry IDs. | POST /board/{boardId}/trash/rows/restore |
get_row_markdown | Read 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_markdown | Write 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 |
Search
Scope: workspace-level (results filtered by token permissions).
| Tool | Description | Public API capability |
|---|---|---|
search | Cross-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).
| Tool | Description | Public API capability |
|---|---|---|
search_docs | Full-text search across documents with ranked hits and highlights. | GET /docs/search |
get_docs_tree | Browse the document hierarchy; omit parentId for root, bound with depth. | GET /docs/tree |
get_doc | Document metadata (title, icon, cover, owner, parent, timestamps) by docId. | GET /docs/{docId} |
get_doc_content | Full markdown body of a document by docId (can be large). | GET /docs/{docId}/md |
create_doc | Create a document with a title, optional parentId and seed content. | POST /docs/ |
set_doc_content | Write 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_metadata | Update a document's title, icon, and/or cover (not the body). | PATCH /docs/{docId} |
delete_doc | Delete a document by docId (owner only). No undo. | DELETE /docs/{docId} |
Notifications
Scope: access_notifications (for the token's own user).
| Tool | Description | Public API capability |
|---|---|---|
list_notifications | List the token user's notifications with unreadCount; id-cursor paginated (after/before). | GET /notifications/ |
update_notification | Mark one notification read or unread by notificationId. | PATCH /notifications/{notificationId} |
delete_notification | Delete one notification by notificationId. No undo. | DELETE /notifications/{notificationId} |
Chat
Scope: access_channels.
| Tool | Description | Public API capability |
|---|---|---|
list_channels | List channels and DM conversations; filter by query/type/kind/participantId; offset-paginated. | GET /chat/channels |
send_message | Send 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.
| Tool | Description | Public API capability |
|---|---|---|
list_row_comments | List 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_comment | Add 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_comment | Mark a file comment done or reopen it. | POST …/row/{rowId}/comment/{commentId}/resolve |
update_row_file | Rename or describe a FILE-column attachment. | PATCH …/row/{rowId}/column/{columnId}/file/{fileId} |
get_row_attachment_url | Resolve 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).
| Tool | Description | Public API capability |
|---|---|---|
get_drive_tree | Browse the drive as a nested file/folder tree; depth-bounded, with truncation drill-down. | GET /drive/tree |
search_drive | Full-text search across drive files and folders. | GET /drive/search |
get_drive_item | Metadata for a single file or folder by fileId. | GET /drive/files/{fileId} |
get_drive_download_url | Time-limited presigned CloudFront download URL for a file (no auth needed to fetch). | GET /drive/files/{fileId}/download |
create_drive_folder | Create a folder at root or under a parentId. | POST /drive/folders |
Export
Scope: access_boards.
| Tool | Description | Public API capability |
|---|---|---|
export_table | Render 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.
| Tool | Description | Public API capability |
|---|---|---|
get_artifact_handoff | The 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_artifacts | List Designs you can open; scope is mine or shared, optional search, cursor-paginated (after, limit up to 50). | GET /artifacts/ |
get_artifact | The 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_versions | The Design's version history; cursor-paginated (after, limit up to 50). | GET /artifacts/{artifactId}/versions |
get_artifact_version | Pages, shared design, and file list of one version (versionId). A version never changes once saved. | GET …/versions/{versionId} |
read_artifact_source | Read 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_preview | Preview of one page (pageId) of a version. | GET …/versions/{versionId}/pages/{pageId}/preview |
get_artifact_design_snapshot | A 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_starters | The 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_systems | The 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_setup | Check 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_assets | Logos, fonts, images, and references added to the Design's shared design. | GET /artifacts/{artifactId}/design-assets |
import_artifact_asset | Add 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_source | Edit 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_requests | Recent edit requests on the Design, with their status and the version each one produced. | GET /artifacts/{artifactId}/requests |
get_artifact_request | Status of one edit request (requestId) and the exact version it produced. | GET /artifacts/{artifactId}/requests/{requestId} |
create_artifact | Create 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/ |
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
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.
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.
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.