How to Connect Claude / Cursor / GPT to Chainsaw via the Built-in MCP Server

Intermediate 20 minutes ML Platform Engineers / Security Engineers / Developers AI Assistant

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. Add mcp:notify only if you want the agent to be able to fire route_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 and the
       transitive count cleared per upgrade.

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 call chainsaw_query_inventory and respond with the score.
Check /api/audit?event=mcp.tools_call — every agent call appears with full params.

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”.