Connect Claude Code

Wire the Pileless MCP server into Claude Code and your agent can push decisions to your inbox — then resume itself when you decide. About two minutes.

Heads up (draft): the @pileless/mcp-server package is being published to npm. Until it's live, run it from source (see the note in step 2). These instructions are the final shape.

1. Get your Pileless API key

Each agent authenticates with a workspace API key (ak_…). Grab one from Pileless → Settings → API keys, or run the helper which opens your browser and writes the key locally:

npx @pileless/mcp-server login

That writes ~/.pileless/config.json. You can also set PILELESS_API_KEY in your environment instead.

2. Add the MCP server to Claude Code

Add Pileless to your MCP servers — either with the CLI:

claude mcp add pileless -- npx -y @pileless/mcp-server

…or by hand in your Claude Code config (~/.claude.json or the project .mcp.json):

{
  "mcpServers": {
    "pileless": {
      "command": "npx",
      "args": ["-y", "@pileless/mcp-server"],
      "env": { "PILELESS_API_KEY": "ak_…" }
    }
  }
}

Running from source (until the npm package is live): clone the Pileless MCP server, npm install && npm run build, then point command at node and args at the built dist/index.js.

3. Verify the connection

Restart Claude Code and run /mcp — you should see pileless connected with its tools. Or just ask your agent: "create a test pile to approve, and give me the link." A pile should land in your inbox.

4. Use it

Now your agent piles instead of stopping to ask. Tell it (or put in your project's agent instructions):

When you're about to send, post, publish, refund, or commit something —
or you have 2+ options for me to choose from — create a Pileless pile
and wait for my decision instead of guessing.

The agent calls pile.create, optionally pile.wait_for_resolution, and resumes the moment you decide.

Tools reference

Tool	What it does
`pile.create`	Submit a new pile of decisions (one or many items).
`pile.add_item`	Append an item to an open pile (live-pile model).
`pile.seal`	Close a pile to further appends.
`pile.wait_for_resolution`	Long-poll for the human's decisions (default 60s).
`pile.status`	Probe a pile's current state.
`pile.capture_url`	Capture a URL's content into a pile item.

Next: connect Codex →