Claude Code

Connect Audity to Claude Code via MCP (auto-configured by npx @auditynow/connect) or call the REST API directly.

Fastest way: one command

npx @auditynow/connect

This auto-configures the Audity MCP server in Claude Code and optionally installs a /audit skill for the Guided Audit Conductor. Skip to Verify it works below.

For details on the connect command, scope flags, and manual setup, see Connect with one command.

Manual MCP setup (if you prefer)

If you want to configure Claude Code manually:

1. Get a Personal Access Token

Go to Settings → API Tokens in your Audity workspace and create a token with Read + Write scopes. It starts with aky_ and is shown only once.

2. Add the MCP server

Claude Code manages MCP servers through its own claude mcp CLI. Register Audity with:

claude mcp add --transport http --scope user \
  audity https://app.auditynow.com/api/mcp \
  --header "Authorization: Bearer aky_your_token_here"

--scope user adds it globally for every project; use --scope project to add it to a single repo’s .mcp.json instead.

3. Reload and test

Start a new Claude Code session (it loads MCP servers at startup), then ask:

List my Audity projects.

Claude Code will call audity_list_projects and return your real projects. You now have 100+ audity_* tools as first-class operations with typed parameters and schema validation.

Optional: Direct API via CLAUDE.md (no MCP dependency)

If you need zero external dependencies or docs.auditynow.com isn’t reachable, Claude Code can call the Audity REST API directly using Bash.

1. Set your token as an environment variable

export AUDITY_TOKEN="aky_your_token_here"

For a one-off session:

AUDITY_TOKEN="aky_your_token_here" claude

2. Add the Audity context to your CLAUDE.md

Copy this into your global ~/.claude/CLAUDE.md or your project’s CLAUDE.md:

## Audity API

Base URL: https://app.auditynow.com
Auth: `Authorization: Bearer $AUDITY_TOKEN`
Full spec: https://docs.auditynow.com/api-reference/openapi.json

Key endpoints:
- GET  /api/user/current                        verify token
- GET  /api/user/credits                        credit balance
- GET  /api/projects                            list all projects
- POST /api/projects                            create project (1,000 credits)
- GET  /api/projects/{id}                       project detail
- POST /api/projects/{id}/audit-analysis        (sync, ~10-15 min; avoid, use async)
- POST /api/agent/projects/{id}/audit-analysis/async  enqueue analysis
- GET  /api/agent/jobs/{id}                     poll job status
- GET  /api/projects/{id}/opportunities         AI-generated opportunities
- GET  /api/projects/{id}/deliverables          full deliverable output
- GET  /api/lead-generation/leads               list ReadyLink leads
- POST /api/lead-generation/leads/{id}/convert  convert lead to project
- POST /api/nucleus/capture/note                submit text/transcript
- GET  /api/nucleus/memories                    search persistent memory
- GET  /api/nucleus/contacts                    lightweight CRM

Errors:
- 401 PAT_MALFORMED: token format wrong
- 401 (no code): token revoked
- 403 PAT_SCOPE_INSUFFICIENT: need write scope
- 429: rate limited

Verify it works

Ask Claude Code:

List my Audity projects and show me which ones have completed analysis.

If Claude returns real data, you’re connected. If it says “I don’t have access to Audity” or returns 401/403, jump to Troubleshooting.

Using the /audit skill (Claude Code only)

If you installed the /audit skill via connect, use it for guided workflow:

/audit Start an audit for "Acme Corp", mid-market manufacturing. 
Run a comprehensive analysis. Summarize top three opportunities.

The /audit skill auto-orchestrates the pipeline (step order, cost preview, job polling, confidence flagging). See Guided Audit Conductor for details.

Example prompts (MCP or direct API)

List my Audity projects and show me which ones have completed analysis.

Create a new Audity project for "Meridian Healthcare", healthcare industry,
50-200 employees. Run the audit analysis. When it finishes, summarize the
top three opportunities by impact score.

Pull my Audity leads from this week with an AI readiness score above 70.
Show me the business name, score, and survey status for each.

Search my Audity Nucleus memories for anything tagged as a client pattern
across healthcare engagements. Include confidence scores.

Troubleshooting

Claude Code says Audity tools aren't available (MCP path)

Run claude mcp list to confirm the server is registered. If it’s listed but tools don’t appear, start a new Claude Code session (MCP servers load at startup). Check that app.auditynow.com/api/mcp is reachable.

Claude says it doesn't know the Audity API (CLAUDE.md path)

Confirm the file is at ~/.claude/CLAUDE.md (global) or at your project root. Start a new Claude Code session after saving.

401 on every request (direct API path)

Run echo $AUDITY_TOKEN. If it’s empty, add the export to your shell profile and reload, or prefix the session with AUDITY_TOKEN=aky_... claude.

401 PAT_MALFORMED

Token format is wrong. Check that your header is exactly Authorization: Bearer aky_<token> (no double Bearer).

403 PAT_SCOPE_INSUFFICIENT

Token lacks write scope. Generate a new token in Settings → API Tokens with Read + Write checked.

What’s next

• Run a full audit workflow, the end-to-end recipe from intake to deliverables
• Working with Nucleus, memories, captures, insights, contacts
• Authentication, token scopes, rotation, error codes