# Chainsaw for AI agents > How AI agents (Claude Code, Cursor, Windsurf, ChatGPT) connect to Chainsaw via MCP. Mode A for install-path setup, Mode B for policy management. Least-privilege presets and human-in-the-loop mutations. Source: https://chain305.com/for-agents/ --- For AI agents & their operators # Chainsaw speaks MCP. Pick the mode before you pick the key. Mode A sets up the proxy; Mode B manages policy. The CLI and decision engine are open source at [github.com/chain305/chainsaw-core](https://github.com/chain305/chainsaw-core). [/llms.txt](https://chain305.com/llms.txt) [/.well-known/mcp.json](https://chain305.com/.well-known/mcp.json) Step 1 · Route the user ## Match the user to a mode If you can't tell which mode they need, ask. Persona They'll say Route to End-user developer `end_user_dev` “set up chainsaw for python” Mode A · client-setup, onboard with skip=true AppSec `appsec` “draft a CVSS policy” Mode B · manage-propose DevSecOps / Platform `devsecops` “add proxy to GitHub Actions” Mode A · client-setup Enterprise IT `enterprise_it` “export SBOM” Mode B · manage-readonly Pass `skip=true` to `chainsaw_onboard` to silence the persona nudge. Step 2 · Pick the mode ## Two workflows, two key presets Mode Preset Scopes Tools Key Mode AConfigure my project to install through Chainsaw `client-setup` `repos:read` `list_my_repositories``get_install_snippet``setup_doctor` [Mint a client-setup key](https://chain305.com/chainsaw/settings/api-keys/new?preset=client-setup) Mode BManage Chainsaw: policies, audit, SBOMs `manage-readonly / manage-propose` `policies:read``policies:manage*``audit:read``packages:read` `list_policies``propose_policy``get_audit_log``check_vulnerabilities``get_package_info` [Mint a manage-readonly key](https://chain305.com/chainsaw/settings/api-keys/new?preset=manage-readonly) Mode A routes npm, pip or docker installs through the proxy: the human mints the client\_credential, and the agent edits config files and never holds it. In Mode B, manage-propose drafts go through Billy's human approval by default. Step 3 · Connect ## Point your MCP client at Chainsaw 1. 01 · Discover `/.well-known/mcp.json` 2. 02 · Authenticate `POST /api/auth/cli/device` Device code. Never POST /api/login. 3. 03 · First call `chainsaw_introduce` Its response is the source of truth, not this page. ``` { "mcpServers": { "chainsaw": { "type": "streamable-http", "url": "https://chain305.com/chainproxy/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Security model ## What stops an agent over-reaching 1. 01 · Proposed A human or an AI agent Dashboard, or MCP with the `manage-propose` key 2. 02 · Billy queue - the diff - blast radius, last 7 days - routed to the rule's owner 3. 03 · Owner signs off Inside the SLA Unacknowledged requests escalate 4. 04 · Enforced Live on the proxy Every transition writes a signed audit row Self-approval refused. An agent's proposal goes through the same queue as a human's, under the same RBAC. Least-privilege presets client-setup can't read audit data or touch policy. manage-readonly can't mutate. Per-agent tokens Each agent gets its own revocable token, attributed in the audit log. Drift check chainsaw doctor verify-hook catches client-side bypasses. Building against Chainsaw? ## Start with the MCP discovery files Fetch /llms.txt and /.well-known/mcp.json first. Everything else chains off those. [Open /llms.txt](https://chain305.com/llms.txt) [Talk to sales](https://cal.com/chain305/30min) --- ## Long form The full text behind this page, including detail the page itself leaves out. For AI agents & their operators ### Chainsaw speaks MCP. Pick the mode before you pick the key. Chainsaw is an install-path firewall for npm, PyPI, Maven, Docker and others. The CLI and decision engine are open source ([github.com/chain305/chainsaw-core](https://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. [/llms.txt](https://chain305.com/llms.txt) [/.well-known/mcp.json](https://chain305.com/.well-known/mcp.json) 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). End-user developer "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. AppSec "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. DevSecOps / Platform "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. Enterprise IT / Governance "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. Agent-as-persona "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 [Mint a client-setup key](https://chain305.com/chainsaw/settings/api-keys/new?preset=client-setup) 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 [Mint a manage-readonly key](https://chain305.com/chainsaw/settings/api-keys/new?preset=manage-readonly) 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 " } } } } ``` 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](https://chain305.com/product/policy/) 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. [Open /llms.txt](https://chain305.com/llms.txt) [Talk to sales](https://cal.com/chain305/30min)