> ## 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
* 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 where you know exactly which endpoint to hit.

## A. MCP Client Tool (recommended for AI agents)

n8n exposes Audity tools to its AI Agent node via the **MCP Client Tool** sub-node. The node connects to an MCP server, enumerates available tools, and lets the AI Agent invoke them.

<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="Configure the MCP server">
    * **Endpoint**: `https://docs.auditynow.com/mcp`
    * **Auth**: Header Auth credential, header `Authorization`, value `Bearer aky_<your-token>`
    * Save the credential in n8n's credential store rather than inlining the token in the node config.
  </Step>

  <Step title="Verify tool discovery">
    Run the workflow once. The AI Agent should list Audity's tools (`listProjects`, `triggerAuditAnalysis`, `listMemories`, etc.) in its execution preview. If it lists nothing, the connection failed, check the troubleshooting accordions below.
  </Step>
</Steps>

## B. HTTP Request node (deterministic workflows)

For workflows where you know exactly which endpoint to call and don't need an LLM in the loop:

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

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

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

  <Step title="Set body and query as needed">
    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 (listInsights, unreadOnly=true)
  → MCP Client Tool (listCaptures, since 24h ago)
  → AI Agent (synthesize a 5-bullet brief)
  → Slack (post to #audity-brief)
```

The AI Agent stitches the two tool outputs together. With Audity's tools attached to the agent, the prompt is just "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/projects/{auditId}/audit-analysis with 360s timeout)
      → Slack (notify: "audit started for {clientName}")
```

Two rate limits to respect in a loop:

* Writes: 20/min (your conversion and analysis calls eat into this)
* Async job polling: 120/min

For a 10-lead batch, expect the workflow to run at least several minutes because synthesis is long-running. If your converted projects already have current document and interview analyses, you can swap the synchronous analysis call for `POST /api/agent/projects/{auditId}/audit-analysis/async` plus `GET /api/agent/jobs/{jobId}` polling.

## Recipe: Capture meeting notes from a transcription service

```
Webhook (from your transcription service)
  → Function (extract transcript text and projectId from payload)
  → 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 summary to consultant)
```

Capture submissions are rate-limited to **30 per hour** per token, plenty for a typical consultant's call volume.

## Tips

* **Store your token in n8n credentials**, not in node config. Credentials are encrypted at rest; node configs aren't.
* **Use one PAT per n8n instance** so revocation only affects that instance. If a workflow leaks, you revoke one token.
* **Wrap mutating workflows in error nodes** that catch 429 and back off. Don't blindly retry, `Retry-After` is in the response header.
* **For batch fan-out, prefer Sequential mode** in the Loop node. n8n's parallel mode will trip rate limits faster than you can blink.

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP Client Tool can't connect to docs.auditynow.com/mcp">
    Verify the endpoint with `curl https://docs.auditynow.com/mcp` from the n8n host. If you self-host n8n behind a corporate proxy, MCP traffic may need an outbound firewall rule for `*.auditynow.com`.
  </Accordion>

  <Accordion title="401 PAT_MALFORMED on every call">
    Your header value probably has an extra `Bearer ` (i.e. you set the header name to `Bearer Authorization`, or the value to `Bearer Bearer aky_...`). The header should be exactly `Authorization: Bearer aky_<token>`.
  </Accordion>

  <Accordion title="403 PAT_SCOPE_INSUFFICIENT on writes">
    Token lacks `write` scope. Generate a new token, 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. For audit analysis, use the async endpoint only when the project already has current document and interview analyses.
  </Accordion>

  <Accordion title="Audit analysis HTTP node times out">
    The default n8n HTTP timeout is shorter than 300s. Set the node's timeout to **360 seconds** or higher and verify with `GET /api/projects/{id}/audit-analysis` before re-triggering. If the project already has current document and interview analyses, you can use `POST /api/agent/projects/{id}/audit-analysis/async`, then poll `GET /api/agent/jobs/{jobId}`.
  </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)