Authentication

@plainwork/mcp authenticates to the Plainwork HTTP API with a per-agent API key. Each key belongs to one agent — a first-class user in the workspace with its own display name, avatar, attribution, and (optionally) auto-approve setting.

Create an agent and mint a key

1. Open Plainwork and sign in.
2. Go to Settings → Agents → New agent.
3. Name the agent after the host (e.g. "Claude Desktop", "n8n staging"). The name appears on every page the agent touches.
4. Copy the pw_agent_… token.

The token is shown once. Plainwork stores a hash; the raw token is not recoverable. Lose it and you mint a new one.

The token format

Every agent API key starts with the literal prefix pw_agent_ followed by a random suffix. The server validates the prefix at startup — a missing or malformed prefix aborts with "invalid environment". Do not wrap the token in quotes, do not prefix it with Bearer yourself; both the stdio and HTTP transports attach Authorization: Bearer <token> for you.

Pass the key to the server

Stdio (NPM)

Set PLAINWORK_API_KEY in the MCP entry of your host config. Each host's guide shows the exact JSON:

• Claude Desktop
• Claude Code
• Cursor

Self-hosted HTTP

Set PLAINWORK_API_KEY in the process environment (or as a Docker -e PLAINWORK_API_KEY=… flag). The HTTP transport uses one key for all incoming requests to that process. If you need per-agent isolation, run one process per agent.

Pointing at a non-default API

PLAINWORK_API_URL overrides the base URL. Keep the /v1 suffix; the client appends paths like /collections directly. Example for a self-hosted instance:

PLAINWORK_API_KEY=pw_agent_... \
PLAINWORK_API_URL=https://plainwork.internal/v1 \
  npx -y @plainwork/mcp

Rotate or revoke

In Settings → Agents, open the agent and click Rotate to mint a new token (the old one is invalidated immediately), or Revoke to kill the key entirely. A revoked key returns 401 from the API on the next call, and all in-flight requests fail with Plainwork API error (401). The agent's past attribution is preserved.

Auto-approve

By default, agent writes are queued for human approval. Flip Auto-approve on an agent once you trust it. With auto-approve on, create_page / update_page / delete_page / move_item apply immediately and the tool response says Page created: …. With auto-approve off (the default), the response says "Proposal submitted — awaiting approval" and the action sits in the workspace's pending inbox until a human resolves it.

See Pending approval for what to do when the inbox queue is surprising your users.