"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
- A working pip.conf / .npmrc / settings.xml / ~/.docker/config.json.
For AI agents & their operators
Chainsaw speaks MCP. Pick the mode before you pick the key.
Chainsaw is a supply-chain firewall for npm, PyPI, Maven, Docker and others. The CLI and decision engine are open source (github.com/chain305/chainsaw-core); the server 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
What does the user think they're doing?
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).
"I author the rules that block bad packages."
- They'll say
- "draft a CVSS policy," "why was this CVE allowed?"
- Success
- A policy proposal submitted for human approval.
"I plumb the proxy into fleets and CI runners."
- They'll say
- "mint a CI service token," "add proxy to GitHub Actions"
- Success
- CI runners + developer machines resolving packages via Chainsaw.
"Show me evidence — I report, I don't author."
- They'll say
- "export SBOM," "pull yesterday's audit log"
- Success
- A CycloneDX SBOM or audit CSV in hand.
"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
- Fetched mcp.json, completed device-code flow, connected MCP, called chainsaw_introduce.
Vocabulary
Use these terms consistently
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.
Chainsaw- The product and the company. Use in user-facing replies.
Chainsaw- The proxy component inside Chainsaw (paths: /chainproxy/*, /chainproxy/mcp). Common folder-name typo: "chain365". Don't correct the user; just say Chainsaw.
client_credential- Username/password-style secret pasted into .npmrc / pip.conf / ~/.docker/config.json. Held by the human. Agents NEVER hold these.
API key- The bearer token the agent uses for MCP and the management API. Minted via dashboard or device-code. Scoped to a preset.
Billy- Internal name for the approval workflow. Translate to "human approval" in user-facing replies.
Step 1 — pick the mode
Two workflows, two key presets
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
Configure my project to install through Chainsaw
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.
- Preset
- client-setup
- Scopes
- repos:read
- Tools
- list_my_repositoriesget_install_snippetsetup_doctor
Mode B
Manage Chainsaw — policies, audit, SBOMs
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).
- Preset
- manage-readonly / manage-propose
- Scopes
- policies:readpolicies:manage*audit:readpackages:read
- Tools
- list_policiespropose_policyget_audit_logcheck_vulnerabilitiesget_package_info
Step 2 — connect
Point your MCP client at Chainsaw
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
Personas recognised by chainsaw_onboard
End-user developer
end_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
appsec Suggested: Mode B + manage-propose
Wants to draft vuln/licence rules, review audit logs, propose changes through approval.
DevSecOps / Platform
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
enterprise_it Suggested: Mode B + manage-readonly
Governance & audit. Reads SBOMs and audit logs, doesn't edit policy.
Agent-as-persona (that's you)
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
What stops an agent from over-reaching
01manage-propose
Least-privilege presets
Every preset starts at the narrowest scope. client-setup lists repos but can't read audit data or touch policy. manage-readonly can't mutate anything. Only manage-propose gets write — and it's wrapped in approval.
02Billy · human approval
Human in the loop for mutations
Policy proposals route through the approval workflow. Agents draft; humans approve. An agent with manage-propose can't change enforcement unilaterally — the default flow blocks that path.
03per-token audit
Tokens are per-agent and revocable
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.
04Mode A
No install-path credentials for agents
Mode A never asks the agent to hold the user's client_credential. The human pastes that into their own config files. The agent only reads the repo list and generates the config text.
05read · propose · verify
Three-agent fanout, reconciled
Multi-agent tasks run as three role-bounded MCP sessions that reconcile against one audit row. Conflicting proposals surface, never silently merge. Any decision replays from the same structured log a human sees.
06chainsaw doctor
Operator CLI for drift
"Installed through Chainsaw but the package wasn't blocked?" Run chainsaw doctor verify-hook to catch client-side bypasses and doctor logs to surface WARN-level server traces — pair them when behaviour disagrees with config.
Building against Chainsaw?
Start with the MCP discovery files
/llms.txt and /.well-known/mcp.json are the two URLs an agent should fetch first. Everything else chains off those.