Chainsaw is a supply-chain firewall for npm, PyPI, Maven, Docker and others. It exposes an MCP server so agents can help users set up the proxy (Mode A) or manage the policy surface (Mode B). These are two different jobs with two different key presets — this page helps you pick the right one.
Mental models
Chainsaw serves five personas, each with a different mental model. Match the user's utterance to a persona BEFORE picking a mode — mis-routing wastes the user's time (and, in the transcript that prompted this page, turned a five-minute setup into four turns of dead-end help).
In their head: "I want `pip install` / `npm install` to go through Chainsaw."
They'll say: "set up chainsaw for python," "do it for me," "install chainsaw in this repo"
Success looks like: A working pip.conf / .npmrc / settings.xml / ~/.docker/config.json.
In their head: "I author the rules that block bad packages."
They'll say: "draft a CVSS policy," "why was this CVE allowed?"
Success looks like: A policy proposal submitted for human approval.
In their head: "I plumb the proxy into fleets and CI runners."
They'll say: "mint a CI service token," "add proxy to GitHub Actions"
Success looks like: CI runners + developer machines resolving packages via Chainsaw.
In their head: "Show me evidence — I report, I don't author."
They'll say: "export SBOM," "pull yesterday's audit log"
Success looks like: A CycloneDX SBOM or audit CSV in hand.
In their head: "I'm headless — no browser, no cookies, no Turnstile widget I can solve."
They'll say: (no user utterance — this is the agent's own mental model)
Success looks like: Fetched mcp.json, completed device-code flow, connected MCP, called chainsaw_introduce.
Vocabulary
The product name is Chainsaw; the proxy inside it is Chainsaw. A
client_credential goes into pip.conf, an
API key is your own bearer token. Two different
secrets, two different owners — conflate them and you'll ask the
user for the wrong thing at the wrong moment.
ChainsawChainsawclient_credentialAPI keyBillyStep 1 — pick the mode
If you don't know which mode the user needs, ASK THEM. Getting this wrong wastes the user's time on the wrong setup.
Mode A
The user wants `npm install`, `pip install`, or `docker pull` to flow through the Chainsaw proxy so every install is policy-checked. End state: a `client_credential` in `.npmrc` / `pip.conf` / `~/.docker/config.json` / `~/.m2/settings.xml`. The human mints the credential in the dashboard; the agent edits config files.
Mint a client-setup keyMode B
The user wants to inspect or change Chainsaw itself. The agent calls the management API via MCP. Pick `manage-readonly` to look around, `manage-propose` to draft policy changes (routed through Billy's human-approval flow by default).
Mint a manage-readonly keyStep 2 — connect
Once the user has minted a key in the dashboard, configure your MCP client to connect over Streamable HTTP with a bearer token.
{
"mcpServers": {
"chainsaw": {
"type": "streamable-http",
"url": "https://chain305.com/chainproxy/mcp",
"headers": { "Authorization": "Bearer <TOKEN>" }
}
}
}
The first tool to call is chainsaw_introduce. It returns
the live mode framing, the preset catalog, and — after the user
identifies themselves via chainsaw_onboard — a
persona-tailored recommended path. Treat its output as the source of
truth; this page can drift, that response can't.
Step 3 — identify the persona
chainsaw_onboardend_user_dev Suggested: Mode A + client-setup (no persona recorded)
Most common cold walk-in. Just wants `pip install` / `npm install` to go through Chainsaw. Call chainsaw_onboard with skip=true so the persona nudge doesn't block them.
appsec Suggested: Mode B + manage-propose
Wants to draft vuln/licence rules, review audit logs, propose changes through approval.
devsecops Suggested: Mode A + client-setup
Wants to get package managers pointed at the proxy across repos and CI. Org-scale flavour of end-user dev.
enterprise_it Suggested: Mode B + manage-readonly
Governance & audit. Reads SBOMs and audit logs, doesn't edit policy.
agent Suggested: Fetch /.well-known/mcp.json, then POST /api/auth/cli/device
Not a persisted persona value. Named here so you — the agent — recognise yourself in this list. Headless, no browser, no Turnstile widget. Never POST /api/login.
Or pass skip=true to silence the onboarding nudge.
Security model
Every preset starts with the narrowest scope that makes the workflow possible. `client-setup` can list repos but cannot read audit data or touch policy. `manage-readonly` cannot mutate anything. Only `manage-propose` gets write access — and it's wrapped in approval.
Policy proposals route through Billy, the approval workflow. Agents draft; humans approve. An agent with manage-propose cannot unilaterally change enforcement — the default flow blocks that path.
Each agent instance gets its own bearer token. Revoke any single token from the dashboard without touching the rest. Activity is attributed to the token in the audit log.
Mode A explicitly does NOT ask the agent to hold the user's `client_credential`. The human pastes that credential into their own config files. The agent only reads the repo list and generates the config text.
Multi-agent tasks against Chainsaw run as a fanout of three role-bounded MCP sessions (read, propose, verify) whose outputs reconcile against a single audit row. Conflicting proposals are surfaced, not silently merged. Operators can replay any decision because the reconciled trace lands in the same structured audit log a human sees.
When an agent reports "I installed through Chainsaw but the package wasn't blocked," run `chainsaw doctor verify-hook` to catch client-side bypasses and `chainsaw doctor logs` to surface WARN-level server traces — pair them when a finding disagrees with config.
Building against Chainsaw?
/llms.txt and /.well-known/mcp.json are the two URLs an agent should fetch first. Everything else chains off those.