CoworkCanvas Docs

index

2 min read

CoworkCanvas Documentation

CoworkCanvas is a flexible, schema-driven work management platform. Admins configure item types, fields, and workflows — AI agents interact with everything via MCP tools.

Demo app: https://demo.coworkcanvas.com MCP server: https://demo-mcp.coworkcanvas.com GraphQL endpoint: https://demo.coworkcanvas.com/graphql MCP protocol version: 2024-11-05 MCP tools available: 7

I want to…

GoalStart here
Connect an AI agent (Claude, ChatGPT, Copilot, etc.)oauth.md
Use a personal API token for testingjwt-tokens.md
Understand what MCP tools are availableoverview.md
Call MCP tools from my agentsuggest_change.md, query_data.md
Understand the platform data modelitems-and-item-types.md
Understand why AI can’t write directlysuggestions-pattern.md
Set up item types as an adminitem-types.md
Get started quickly (5 minutes)quickstart.md
See GraphQL query examplesquery-examples.md
Read AI-agent-specific guidanceAGENTS.md
Set up platform-specific agent skillsoverview.md

File Index

Getting Started

FileDescription
quickstart.mdFastest path from zero to a working MCP call

Concepts

FileDescription
items-and-item-types.mdCore data model: items, item types, and the schema-driven architecture
fields.mdAll 13 field types with accepted value formats
workflows-and-steps.mdWorkflow and step model
suggestions-pattern.mdAI safety model: why all writes require human approval

MCP Tools

FileDescription
overview.mdEndpoints, transport modes, auth, tool list
get_schema.mdDiscover item types and fields
suggest_change.mdPropose create/update/delete changes
query_data.mdRead data via GraphQL
get_current_context.mdGet the user’s current page context
get_step_context.mdGet deep details on a workflow step
upload_document.mdUpload a file to a workflow step
link_document.mdLink an external URL to a workflow step

Authentication

FileDescription
overview.mdTwo auth methods compared side-by-side
jwt-tokens.mdPersonal API tokens for testing and direct use
oauth.mdOAuth 2.1 + PKCE flow for AI platform integrations

Admin

FileDescription
item-types.mdCreating and configuring item types and fields
oauth-clients.mdRegistering OAuth clients for AI integrations

Skills

FileDescription
overview.mdWhat skills are, categories, and how to use them
README.mdSkill templates for Claude (Anthropic) agents
README.mdSkill templates for OpenAI (ChatGPT, GPTs) agents
README.mdSkill templates for Google Gemini agents
README.mdSkill templates for Microsoft (Copilot Studio) agents

GraphQL

FileDescription
query-examples.mdCopy-paste GraphQL queries for common operations

Key Facts

PropertyValue
MCP endpointPOST https://demo-mcp.coworkcanvas.com/mcp
GraphQL endpointPOST https://demo.coworkcanvas.com/graphql
Auth headerAuthorization: Bearer {token}
OAuth discoveryGET https://demo-mcp.coworkcanvas.com/.well-known/oauth-authorization-server
ProtocolJSON-RPC 2.0 over HTTP
MCP spec version2024-11-05

Common Pitfalls

  1. Calling suggest_change without knowing the schema. Always call get_schema first so you know available item type slugs, field keys, and valid SELECT option values. Passing an unknown field key or invalid option value will fail.

  2. Using mutations in query_data. The query_data tool only accepts GraphQL queries — mutation and subscription operations are rejected. All writes must go through suggest_change.

  3. Forgetting that writes require human approval. suggest_change creates a pending suggestion — it does NOT apply the change immediately. Always tell the user to visit the previewUrl to approve.

Graph View