> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auditynow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect with One Command

> Use npx @auditynow/connect to automatically set up the Audity MCP server in Claude Desktop, Claude Code, and Cursor.

## What connect does

`npx @auditynow/connect` is a single command that:

1. Opens your browser to approve the connection (loopback handoff to localhost)
2. Mints an Audity Personal Access Token (`aky_...`)
3. Saves the token locally
4. Auto-configures the Audity MCP server in Claude Desktop, Claude Code, and Cursor
5. Prints manual setup instructions for ChatGPT and n8n
6. Verifies the live connection

Re-running connect reuses your saved token (there's a 10-active-token cap per user).

## Installation & quick start

Install Node.js 18+ if you don't have it, then run:

```bash theme={null}
npx @auditynow/connect
```

That's it. Follow the prompts in your browser to approve, then watch connect auto-configure your tools.

## What gets configured automatically

<Steps>
  <Step title="Claude Desktop">
    Auto-configures the MCP server at `https://app.auditynow.com/api/mcp` with your token. No manual steps needed.
  </Step>

  <Step title="Claude Code">
    Runs `claude mcp add` (Claude Code's MCP CLI) to register the server, no manual config needed. Also offers to install a `/audit` skill that triggers the Guided Audit Conductor (default yes).
  </Step>

  <Step title="Cursor">
    Auto-configures Cursor's `~/.cursor/mcp.json` with the MCP server. No manual steps needed.
  </Step>

  <Step title="ChatGPT and n8n">
    Prints manual setup instructions (you copy-paste the URL and token into each platform's UI).
  </Step>
</Steps>

## Scope flags

By default (as of v2.0.0), connect issues a token with **read + write + generate** scope, everything needed to run audits end to end, including AI generation. You can narrow the scope with flags:

```bash theme={null}
npx @auditynow/connect --read-only
```

Scope reference:

| Flag          | Scope                   | Use case                                                                                                                          |
| ------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| (no flag)     | read + write + generate | Standard; agents can create projects, convert leads, and run AI work: audits, document/interview analysis, deliverable generation |
| `--read-only` | read only               | Least privilege; agents can fetch data but not mutate state. Wins if combined with other flags                                    |
| `--write`     | read + write            | Agents act on your data, but no AI generation (no AI spend)                                                                       |
| `--generate`  | read + write + generate | Explicit alias for the default                                                                                                    |

All write and generate operations are gated server-side by your plan and available credits, so a token can't overspend an account that isn't entitled.

## Status and management

Check your token's status:

```bash theme={null}
npx @auditynow/connect status
```

Remove the saved token and disconnect:

```bash theme={null}
npx @auditynow/connect remove
```

To revoke a token entirely, go to **Settings → API Tokens** in your Audity workspace and delete it there.

## MCP server details

After connect runs, the MCP server is live at:

```
https://app.auditynow.com/api/mcp
```

Server name: `audity`

Auth header (connect sets this for you):

```
Authorization: Bearer aky_<your-token>
```

The server exposes 100+ snake\_case `audity_*` tools covering the full audit pipeline: document uploads, interview sessions, async analysis jobs, opportunities, ROI, and deliverables (PDF, Gamma decks, stakeholder memos).

## Claude Code `/audit` skill (opt-in)

Claude Code supports connect's optional `/audit` skill, which turns any connected, instruction-aware agent into a guided conductor. It automatically:

* Calls `audity_get_navigation_status` to check pipeline progress
* Runs steps in order
* Previews cost and time before any paid/generation step and waits for approval
* Polls long jobs (and understands that a finished Gamma/PDF job means generation was TRIGGERED, not that the file is ready)
* Flags findings under 0.8 confidence as hypotheses

The skill is offered automatically while you run `npx @auditynow/connect`: when Claude Code is detected, connect asks whether to also install the `/audit` skill (default yes). In a non-interactive shell it installs automatically. There is no separate flag, it is part of the normal connect run.

Then in Claude Code, use `/audit` to trigger the conductor for a guided workflow.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connect hangs on browser approval">
    connect opens your default browser automatically. If it doesn't, connect prints a one-time approval URL in the terminal, open that link to approve. The URL is tied to your current connect session, so you can't construct it by hand; re-run `npx @auditynow/connect` if it expires.
  </Accordion>

  <Accordion title="Every tool call returns 401 PAT_MALFORMED">
    Token format is wrong. Most common cause: the tool configuration double-prefixed `Bearer Bearer aky_...`. Run `npx @auditynow/connect status` to check your saved token, then `npx @auditynow/connect remove` and re-run to get a fresh one. If the token is correct but the error persists, check your tool's auth header in Settings to confirm it's exactly `Authorization: Bearer aky_<token>`.
  </Accordion>

  <Accordion title="Every tool call returns 403 PAT_SCOPE_INSUFFICIENT">
    Token lacks the required scope, most commonly a token minted with `--read-only` or `--write` being used for work that needs more. Run `npx @auditynow/connect remove`, then re-run with the scope you need:

    * `npx @auditynow/connect` for the full default (read + write + generate)
    * `npx @auditynow/connect --write` if you want writes but no AI spend
    * `npx @auditynow/connect --read-only` if you only read data
  </Accordion>

  <Accordion title="Claude Desktop / Claude Code / Cursor doesn't see Audity tools">
    1. Run `npx @auditynow/connect status` to check if connect is registered.
    2. Restart your tool (Claude Desktop, Claude Code, or Cursor) fully; MCP servers are discovered at startup.
    3. If tools still don't appear, run `npx @auditynow/connect remove` and re-run to reconfigure.
  </Accordion>

  <Accordion title="429 rate limited">
    See [Authentication → Rate limits](/authentication#rate-limits). Most common ceiling: write limits on batch workflows (e.g. converting 10+ leads). Consider serializing operations or adding delays.
  </Accordion>

  <Accordion title="Audit analysis times out">
    Comprehensive audit runs as an async job taking \~10-15 minutes. Enqueue via `audity_enqueue_audit_analysis`, then poll `audity_get_job`. The Guided Audit Conductor handles polling automatically.
  </Accordion>
</AccordionGroup>

## What's next

* [Guided Audit Conductor →](/guides/audit-conductor), pipeline order, confirm-before-spend, job polling
* [Run a full audit workflow →](/guides/running-an-audit), end-to-end recipe
* [Lead conversion playbook →](/guides/lead-conversion), triage and convert from your agent