How to Connect Claude / Cursor / GPT to Chainsaw via the Built-in MCP Server
Wire your AI agent into the Chainsaw control plane with the Model Context Protocol — give the agent inventory queries, patch-simulation, affected-by lookups, and owner routing without writing a custom integration.
What This Gets You
Once Chainsaw is exposed as an MCP server, your agent can answer questions like “are we using anything affected by CVE-2026-4711?” or “what would break if we upgraded lodash to 4.17.22?” with a single tool call instead of a hand-built API integration. The agent already knows how to read JSON-RPC; you just point it at https://chain305.com/chainproxy/mcp and hand it a token.
The four tools available out of the box are:
| Tool | What it does |
|---|---|
chainsaw_query_inventory | Pivots the dependency inventory by package, client, or ecosystem |
chainsaw_query_affected_packages | Walks the SBOM dependsOn graph for a given CVE and returns every transitively-affected package |
chainsaw_simulate_patch | Calls /api/patches/simulate for a candidate upgrade and returns {cleared_cves, unblocked_transitive_count, related_pins} |
route_violation_to_owner | Resolves the CODEOWNERS path for a violation and posts to the owning team via your configured destinations |
These are the same primitives Billy uses internally. Exposing them via MCP just means your agent gets the same level of access.
Prerequisites
- A running Chainsaw control plane reachable from your agent runtime.
- Manager or Admin role to create the client credential.
- An agent that speaks MCP — Claude Code, Cursor, GPT-with-MCP, etc.
Step 1: Mint an AI-Agent Client Credential
Don’t reuse a service token for this — use the dedicated AI-agent credential type so audit logs are clean and you can rotate independently. See How to Issue and Rotate AI-Agent Client Credentials for the full walkthrough. The short version:
- Open Access → Client credentials → New.
- Type:
AI agent. - Scopes:
mcp:read. Addmcp:notifyonly if you want the agent to be able to fireroute_violation_to_owner. - Save the
client_id/client_secret— they will only be shown once.
Step 2: Verify the MCP Endpoint
The MCP endpoint is exposed at POST https://chain305.com/chainproxy/mcp as JSON-RPC 2.0 (the older /chainsaw/mcp path still works as a legacy alias). The discovery document at https://chain305.com/.well-known/mcp.json advertises the same URL. A quick health check:
curl -X POST https://chain305.com/chainproxy/mcp \
-H "Authorization: Bearer $CHAINSAW_AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
You should get back a tools[] array containing the four tools above plus their JSON Schemas.
If the response is a 404 whose content-type is text/html, the request hit the static site, not the API — use the /chainproxy/ prefix.
Step 3: Configure Claude Code
Add Chainsaw to your ~/.claude/settings.json:
{
"mcpServers": {
"chainsaw": {
"transport": "http",
"url": "https://chain305.com/chainproxy/mcp",
"headers": {
"Authorization": "Bearer ${CHAINSAW_AGENT_TOKEN}"
}
}
}
}
Restart Claude Code. The four tools appear under chainsaw_* in the tool palette.
Test:
You: are we using anything affected by GHSA-jr5f-v2jv-69x6?
Claude: [calls chainsaw_query_affected_packages with cve="GHSA-jr5f-v2jv-69x6"]
Yes — six direct packages and twelve transitives. The biggest blast radius
is via @nestjs/core which pulls it in transitively …
Step 4: Configure Cursor
Cursor uses the same MCP config under ~/.cursor/mcp.json:
{
"chainsaw": {
"command": "npx",
"args": [
"@modelcontextprotocol/inspector",
"--http",
"https://chain305.com/chainproxy/mcp",
"--header",
"Authorization: Bearer ${CHAINSAW_AGENT_TOKEN}"
]
}
}
(For stdio transport on a self-hosted relay, swap the args for your relay’s stdio command.)
Step 5: Configure GPT / Other Agents
Any agent that can speak MCP over HTTP works the same way — point it at https://chain305.com/chainproxy/mcp with a bearer token. For agents that only speak OpenAI-style function calling, mint the four tools as functions and proxy them through a thin HTTP wrapper that translates function calls into MCP tools/call invocations.
Step 6: Set the Agent’s Read Boundary
Each MCP tool respects the credential’s scope, so an agent token with only mcp:read cannot fire route_violation_to_owner even if the agent tries. The audit log records every tool call with the full JSON-RPC params, so you can spot-check what the agent has been doing:
curl -H "Authorization: Bearer $CHAINSAW_TOKEN" \
"https://chain305.com/chainproxy/api/audit?event=mcp.tools_call&actor=$AGENT_CLIENT_ID&since=24h" \
| jq '.events[] | {time, tool: .params.name, args: .params.arguments}'
Step 7: Common Agent Workflows
Triage a new CVE (read-only)
You: A new CVE just dropped, GHSA-2hwx-rg2p-7g9j. What's our exposure and what
should we upgrade?
Agent: [chainsaw_query_affected_packages] → 4 packages affected
[chainsaw_query_inventory ...] → which clients install them
[chainsaw_simulate_patch ...] → simulates upgrading the worst
Output: a bullet list with concrete recommended upgrades, the
CVEs each one clears, and any policy pins it no longer matches.
This is one user prompt and three tool calls. Without MCP, it’s a 30-line bash script.
Open a remediation ticket (with mcp:notify)
You: For each KEV-pinned CVE in our supply chain, ping the owning team with
a recommended upgrade.
Agent: [chainsaw_query_affected_packages with kev_only=true]
For each affected package:
[chainsaw_simulate_patch ...] → cleanest upgrade
[route_violation_to_owner ...] → dispatch to CODEOWNERS team
The route_violation_to_owner tool requires mcp:notify scope and a configured destination map (see tutorial 61).
Verification
- Run
tools/list— confirm four tools. - From the agent: “What’s the trust score of
lodash@4.17.21?” — agent should callchainsaw_query_inventoryand respond with the score. - Check
/api/audit?event=mcp.tools_call— every agent call appears with full params.
Related Topics
- How to Issue and Rotate AI-Agent Client Credentials — credential lifecycle.
- How to Use Billy MCP Tools for Triage — the same tools surfaced inside the dashboard chat.
- How to Verify MCP-Server Provenance — the inverse direction; this guide is “trust Chainsaw as an MCP server”, that one is “trust the MCP servers your agents pull from npm”.