> For the complete documentation index, see [llms.txt](https://www.quillaudits.com/quillshield/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.quillaudits.com/quillshield/developers/mcp-for-cursor-and-claude.md).

# MCP for Cursor and Claude

Run QuillAudits from Cursor or Claude. Wallet-only starts; no Stripe from the agent.

Use QuillAudits from an AI agent. Same pricing and coupons as the dashboard — the agent calls tools instead of clicking the UI.

**Package:** `@quillaudits/mcp`\
**Auth:** org API key (`qs_live_…`) — spend uses the **org owner’s** wallet.\
**Payments from the agent:** wallet only. Cards and top-ups stay in the dashboard.

{% stepper %}
{% step %}

### Create an API key

Open [shield.quillaudits.com](https://shield.quillaudits.com) → **Settings → API keys → Create key**. Copy the **Cursor / Claude mcp.json** block shown after create.
{% endstep %}

{% step %}

### Paste into MCP settings

Paste into Cursor MCP settings (or Claude Desktop config). Minimal config:

```json
{
  "mcpServers": {
    "quillaudits": {
      "command": "npx",
      "args": ["-y", "@quillaudits/mcp"],
      "env": {
        "QUILLSHIELD_API_KEY": "qs_live_YOUR_KEY",
        "QUILLSHIELD_API_URL": "https://api.quillaudits.ai"
      }
    }
  }
}
```

Needs Node.js 18+.
{% endstep %}

{% step %}

### Top up if needed, then ask the agent

Top up prepaid balance under **Billing** if you plan to start audits. In chat: *List my QuillAudits projects* or *Check my QuillAudits wallet*.
{% endstep %}
{% endstepper %}

## Money rules

Checkout matches the web app: quote (BLOC / full-audit price) → optional coupon → wallet (prepaid → refund → bonus) → `final_price_cents`.

| `final_price_cents` | What the agent must do                                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `0`                 | Call `pay_quote` or `submit_audit` with **`confirm: true`**                                                                     |
| `> 0`               | Tool returns **`wallet_topup_required`** plus a link to [top up](https://shield.quillaudits.com/topup). **No Stripe from MCP.** |

Without `confirm: true`, a covered quote returns **`confirm_required`** and does not spend credits.

{% hint style="info" %}
**Workflows.** MCP audits run your organization's default workflow (the QuillShield Audit Agent unless an admin changed it) on QuillShield AI. Choose another workflow, or your own AI, in the dashboard's **Workflow** step.
{% endhint %}

## Tools

**Read:** `list_projects`, `list_versions`, `list_audits`, `get_audit`, `list_findings`, `get_report`, `get_wallet`, `get_quote`, `get_order`, `list_orders`.

**Write:** `submit_audit`, `create_quote`, `apply_coupon`, `remove_coupon`, `pay_quote`, `start_audit`, `cancel_audit`, `watch_audit` (short poll cap per call).

Not available: Stripe Checkout, mock-confirm, creating top-up orders, finding chat, or share links.

Typical path: `get_wallet` → `submit_audit` (`pay: false`) → optional `apply_coupon` → `pay_quote` (`confirm: true`) → `watch_audit` → `list_findings` / `get_report`.

## MCP vs CLI vs dashboard

|               | Dashboard          | CLI                 | MCP                         |
| ------------- | ------------------ | ------------------- | --------------------------- |
| Who drives it | You in the browser | You / scripts       | An AI agent                 |
| Coupons       | Yes                | Yes (`--coupon`)    | Yes (`apply_coupon`)        |
| Wallet spend  | Signed-in user     | Org owner (API key) | Org owner (`confirm: true`) |
| Card / Stripe | Yes                | Yes                 | **No** → `/topup`           |

See CLI: install and init and API overview.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.quillaudits.com/quillshield/developers/mcp-for-cursor-and-claude.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
