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:

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

1. Claude Desktop

   Auto-configures the MCP server at https://app.auditynow.com/api/mcp with your token. No manual steps needed.

2. 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).

3. Cursor

   Auto-configures Cursor’s ~/.cursor/mcp.json with the MCP server. No manual steps needed.

4. ChatGPT and n8n

   Prints manual setup instructions (you copy-paste the URL and token into each platform’s UI).

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:

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:

npx @auditynow/connect status

Remove the saved token and disconnect:

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

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.

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

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

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.

429 rate limited

See Authentication → Rate limits. Most common ceiling: write limits on batch workflows (e.g. converting 10+ leads). Consider serializing operations or adding delays.

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.

What’s next

• Guided Audit Conductor →, pipeline order, confirm-before-spend, job polling
• Run a full audit workflow →, end-to-end recipe
• Lead conversion playbook →, triage and convert from your agent