Claude Code

Claude Code manages MCP servers with the claude mcp CLI. Registering @plainwork/mcp is two commands.

Add the server

claude mcp add plainwork -- npx -y @plainwork/mcp

The -- separates the Claude Code flags from the subprocess command. The subprocess inherits the environment of the shell that started Claude Code, so export the credentials first:

export PLAINWORK_API_KEY=pw_agent_…
export PLAINWORK_API_URL=https://api.plainwork.xyz/v1

See Authentication for how to mint a token.

Persist these in your shell profile (~/.zshrc, ~/.bashrc) so every new Claude Code session inherits them.

Verify

From inside Claude Code:

/mcp list

plainwork should appear with status connected. Ask:

List my Plainwork collections.

Claude Code calls list_collections and prints the result.

Remove or rename

claude mcp remove plainwork

Then re-add with a different name or args.

Pinning a version

claude mcp add plainwork -- npx -y @plainwork/mcp@0.1.0

Lock the version when you need reproducible behaviour across a team; leave it bare (@plainwork/mcp) to always pull the latest.

Debugging a registration

If claude mcp list reports plainwork as failed, run the same command directly in a shell to inspect the server's startup output:

PLAINWORK_API_KEY=pw_agent_… npx -y @plainwork/mcp

A missing or malformed API key surfaces as "invalid environment" on the first line — see Invalid token.