Connecting via MCP

Plainwork ships an official Model Context Protocol server, published as @plainwork/mcp. It lets any MCP-compatible agent - Claude Desktop, Claude Code, Cursor, or a custom orchestrator - read, query, and propose writes against your workspace with the same attribution and approval rules as the API.

Quick start

1. Create an agent in Settings → Agents and copy the pw_agent_… token.

2. In your MCP client's config (e.g. claude_desktop_config.json), add:

   {
     "mcpServers": {
       "plainwork": {
         "command": "npx",
         "args": ["-y", "@plainwork/mcp"],
         "env": {
           "PLAINWORK_API_KEY": "pw_agent_…",
           "PLAINWORK_API_URL": "https://api.plainwork.xyz/v1"
         }
       }
     }
   }
   

3. Restart the client. Ask it to list your collections to confirm the connection.

What the agent can do

• Read — list_collections, list_views, read_page, query_pages, search_pages.
• Propose writes — create_page, update_page, delete_page, move_item. Proposals queue as pending actions until a human approves them, unless the agent has Auto-approve enabled.

Troubleshooting

• A tool returns "awaiting approval" — expected. Open the pending-actions inbox to review.
• 401 errors — the token is wrong or the agent was revoked. Rotate it and update the config.
• Nothing happens — confirm the client actually loaded the server; most clients log MCP connection errors to their console.

A full setup guide with per-client snippets ships separately.