Connect n8n

Use Audity inside n8n via the MCP Client Tool node, or call endpoints from HTTP Request nodes.

Requirements

• n8n self-hosted or cloud, with MCP support enabled (or HTTP Request nodes for REST calls)
• An Audity Personal Access Token (aky_...), see Authentication

Two paths

n8n can talk to Audity in two ways. The MCP path is recommended for AI Agent workflows; the HTTP path is fine for deterministic automations.

A. MCP Client Tool (recommended for AI agents)

n8n exposes Audity tools to its AI Agent node via the MCP Client Tool sub-node.

1. Add an AI Agent node

   Add the AI Agent node (LangChain). MCP tools attach to AI Agents, not standalone workflows.

2. Attach an MCP Client Tool sub-node

   On the AI Agent’s “Tool” input, click + and search for MCP Client Tool.

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

4. Configure the MCP server

   • Endpoint: https://app.auditynow.com/api/mcp
   • Auth: Header Auth credential, header Authorization, value Bearer aky_<your-token>
   • Save the credential in n8n’s credential store, not inline.
5. Verify tool discovery

   Run the workflow once. The AI Agent should list Audity’s tools (audity_list_projects, audity_enqueue_audit_analysis, audity_list_memories, etc.) in its execution preview. If it lists nothing, the connection failed; check Troubleshooting.

B. HTTP Request node (deterministic workflows)

For workflows where you know exactly which endpoint to call:

1. Add an HTTP Request node

   • Method: per the OpenAPI spec (e.g. POST for audit enqueue)
   • URL: https://app.auditynow.com/api/...
2. Set authentication

   • Authentication: Generic Credential Type → Header Auth
   • Header Name: Authorization
   • Header Value: Bearer aky_<your-token>

   Store as a credential, not inline.

3. Set body and query

   Match the request shape from the OpenAPI spec. For writes, set Content-Type: application/json and pass the body as JSON.

Recipe: Daily Audity brief in Slack

Schedule (weekday 8am)
  → MCP Client Tool (audity_list_insights, unreadOnly=true)
  → MCP Client Tool (audity_list_captures, since 24h ago)
  → AI Agent (synthesize a 5-bullet brief)
  → Slack (post to #audity-brief)

The AI Agent stitches the tool outputs together. Prompt: “Pull my unread insights and captures from the last day. Summarize as 5 bullets, ranked by urgency.”

Recipe: Auto-triage and convert qualified leads

Schedule (every hour)
  → HTTP Request (GET /api/lead-generation/leads?status=active&sortBy=composite_score&sortOrder=desc&limit=50)
  → Function (filter: compositeScore > 80 AND surveyStatus !== 'converted')
  → Loop (sequential, respect write limits)
      → HTTP Request (POST /api/lead-generation/leads/{id}/convert)
      → HTTP Request (POST /api/agent/projects/{auditId}/audit-analysis/async)
      → HTTP Request (GET /api/agent/jobs/{jobId}) polling loop
      → Slack (notify: "audit started for {clientName}")

Rate limits to respect:

• Writes: 20/min
• Job polling: 120/min

Each audit synthesis runs ~10-15 minutes, so a sequential 10-lead batch that waits for completion takes hours; if you only need to kick off the analyses, notify on enqueue instead of polling to completion. Either way, use the async endpoint + polling rather than holding long HTTP requests.

Recipe: Capture meeting notes from transcription service

Webhook (from transcription service)
  → Function (extract transcript text and projectId)
  → HTTP Request (POST /api/nucleus/capture/note with { content, projectId })
  → Wait (60s for extraction)
  → HTTP Request (GET /api/nucleus/captures/{id})
  → AI Agent (summarize action items from .items)
  → Slack DM (send to consultant)

Capture submissions are rate-limited to 30/hour per token.

Tips

• Store your token in n8n credentials, not node config. Credentials are encrypted; configs aren’t.
• Use one PAT per n8n instance so revocation only affects that instance.
• Wrap mutating workflows in error handlers that catch 429 and back off. Honor Retry-After header.
• Use Sequential mode in Loop nodes for batch operations. Parallel mode trips rate limits fast.

Troubleshooting

MCP Client Tool can't connect to app.auditynow.com/api/mcp

Verify with curl https://app.auditynow.com/api/mcp from the n8n host. If n8n is behind a corporate proxy, you may need an outbound firewall rule for *.auditynow.com.

401 PAT_MALFORMED on every call

Check the header value. It should be exactly Authorization: Bearer aky_<token>. If you have an extra Bearer (double prefix), fix it.

403 PAT_SCOPE_INSUFFICIENT on writes

Token lacks write scope. Generate a new token with both read and write scopes, update the credential in n8n.

429 with bursty Loop nodes

Switch the Loop to Sequential, or add a Wait node between writes. Use async audit endpoint + polling, not synchronous calls.

HTTP node timeout on audit analysis

A comprehensive audit synthesis runs ~10-15 minutes, longer than any sensible HTTP node timeout, and a request held that long can be cut by platform gateways with no indication whether the work completed. Don’t raise the node timeout; use the async endpoint (POST /api/agent/projects/{id}/audit-analysis/async) + polling (GET /api/agent/jobs/{jobId}) instead.

What’s next

• Run a full audit workflow →
• Lead conversion playbook →
• API Quickstart (curl) →