> ## 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 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](/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.

<Steps>
  <Step title="Add an AI Agent node">
    Add the **AI Agent** node (LangChain). MCP tools attach to AI Agents, not standalone workflows.
  </Step>

  <Step title="Attach an MCP Client Tool sub-node">
    On the AI Agent's "Tool" input, click **+** and search for **MCP Client Tool**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](#troubleshooting).
  </Step>
</Steps>

## B. HTTP Request node (deterministic workflows)

For workflows where you know exactly which endpoint to call:

<Steps>
  <Step title="Add an HTTP Request node">
    * **Method**: per the [OpenAPI spec](/api-reference/openapi.json) (e.g. `POST` for audit enqueue)
    * **URL**: `https://app.auditynow.com/api/...`
  </Step>

  <Step title="Set authentication">
    * **Authentication**: Generic Credential Type → **Header Auth**
    * **Header Name**: `Authorization`
    * **Header Value**: `Bearer aky_<your-token>`

    Store as a credential, not inline.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## What's next

* [Run a full audit workflow →](/guides/running-an-audit)
* [Lead conversion playbook →](/guides/lead-conversion)
* [API Quickstart (curl) →](/api-quickstart)