# n8n Setup

> Connect n8n to graph8 via MCP using the remote endpoint with a Bearer API key

Source: https://docs.graph8.com/developers/n8n-setup/

Connect n8n to graph8 to automate workflows with your campaigns, accounts, contacts, and intelligence data.

> **Tip:**
> n8n runs headless, so it does **not** use the interactive browser OAuth flow. Instead it authenticates to the remote graph8 MCP server with a **personal or org API key** sent as an `Authorization: Bearer` header. There is no `session_id` to copy and no config file with a `session_id` — those belonged to a decommissioned setup.

## What is n8n?

[n8n](https://n8n.io) is an open-source workflow automation tool. With the graph8 MCP integration you can:

- Trigger workflows when campaigns, deals, or contacts change
- Sync graph8 data into your CRM or data warehouse
- Build custom automations against graph8's tools and index

## Prerequisites

- An n8n instance (self-hosted or cloud)
- A graph8 account ([get started free](https://auth.graph8.com/en/signup) — 1,000 credits, no card required)
- A graph8 API key:
  - **Personal API key** — **Profile → Developer** (scoped to you inside the active org), or
  - **Org API key** — **Settings → API** (admin only; for shared/service automations)

> **Note:**
> Keep the API key in n8n **Credentials**, not hard-coded in nodes. That way you rotate it in one place. graph8 API keys are long-lived — they do not expire after 24 hours of inactivity, so there is no per-run "session refresh" to manage.

## Setup

There are two ways to call graph8 from n8n. Both point at the same endpoint:

```
https://be.graph8.com/mcp/
```

**MCP Client Tool node**

Recent n8n versions ship a native **MCP Client Tool** node.

1. **Add the MCP Client Tool node** to your workflow (or attach it to an AI Agent node as a tool).

2. **Set the server URL**

```
   https://be.graph8.com/mcp/
```

3. **Set authentication to Header Auth**

   Add a header credential:

   | Field | Value |
   |-------|-------|
   | Name | `Authorization` |
   | Value | `Bearer YOUR_G8_API_KEY` |

   Replace `YOUR_G8_API_KEY` with your personal or org API key (they start with `g8_`).

4. **Select tools and run**

   The node lists the graph8 tools your role grants. Pick a tool (for example `g8_list_campaigns`) and execute the node to verify the connection.

**HTTP Request node**

If your n8n version has no MCP node, call the JSON-RPC endpoint with an **HTTP Request** node:

```json
{
  "method": "POST",
  "url": "https://be.graph8.com/mcp/",
  "headers": {
    "Authorization": "Bearer YOUR_G8_API_KEY",
    "Content-Type": "application/json"
  },
  "body": {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "g8_list_campaigns",
      "arguments": {
        "status": "active"
      }
    },
    "id": 1
  }
}
```

Store the API key as an n8n **Header Auth** credential and reference it from the node rather than pasting it into the body or URL.

## Available Actions

Once connected, your n8n workflows can call any graph8 MCP tool your role grants. Tool names are prefixed with `g8_`. A few common ones:

> **Note:**
> Exact tool names are **mode-dependent**. When the endpoint runs in combined `all` mode, GTM tools are namespaced — e.g. `g8_gtm_list_campaigns` instead of `g8_list_campaigns`. The unprefixed names below are the canonical form; the MCP node lists the exact names your role grants, and you can always confirm them in the [MCP Tool Reference](https://docs.graph8.com/developers/mcp-tools/).

| Tool | Description |
|------|-------------|
| `g8_list_campaigns` | List campaigns with an optional status filter |
| `g8_get_campaign` | Get details for a specific campaign |
| `g8_search_companies` | Search companies already in your CRM |
| `g8_find_companies` | Search graph8's company index for new accounts |
| `g8_search_contacts` | Search contacts already in your CRM |
| `g8_get_deals` | List pipeline deals with stage / text filters |
| `g8_list_intelligence_data` | List intelligence data (scrapes, enrichment, competitor research) |
| `g8_tool_search` | Discover and activate other tools by keyword |

For the complete list with parameters and return shapes, see the [MCP Tool Reference](https://docs.graph8.com/developers/mcp-tools/).

## Example Workflows

### Sync New Campaigns to Slack

1. **Trigger**: Schedule (every hour) or Webhook
2. **graph8 tool**: `g8_list_campaigns` with `status="active"`
3. **Filter Node**: Only new campaigns since the last run
4. **Slack Node**: Post to #marketing

### Enrich CRM with Company Intelligence

1. **Trigger**: Webhook from CRM (new deal created)
2. **graph8 tool**: `g8_find_companies` (or `g8_search_companies`) by name
3. **graph8 tool**: `g8_list_intelligence_data` for the company
4. **HTTP Node**: Update the CRM record with the intelligence data

### Daily Pipeline Report

1. **Trigger**: Schedule (9am daily)
2. **graph8 tool**: `g8_get_deals`
3. **Code Node**: Summarize the pipeline by stage
4. **Email Node**: Send the report to the sales team

## Troubleshooting

n8n specifics live here. Generic MCP issues (auth, permissions, tool names, timeouts) are answered in the [MCP FAQ](https://docs.graph8.com/developers/mcp-faq/).

### Workflow execution errors

- Use n8n's **Execute Workflow** in single-step mode to isolate which node fails
- Inspect the HTTP Request / MCP node response body for the actual server error
- For self-hosted n8n, check the container logs for connection-level errors

### Other issues

- Authentication failed → [FAQ](https://docs.graph8.com/developers/mcp-faq/#authentication-failed-or-401) (check the `Authorization: Bearer` header and that the key is not revoked)
- Tool not found → [FAQ](https://docs.graph8.com/developers/mcp-faq/#tool-not-found)
- Rate limiting (50 rps cap) → [FAQ](https://docs.graph8.com/developers/mcp-faq/#what-is-the-rate-limit)
- Timeouts on long-running tools → [FAQ](https://docs.graph8.com/developers/mcp-faq/#why-does-my-tool-call-time-out)

## Credentials & Keys

- Store the API key as an n8n **Header Auth** credential (`Authorization: Bearer g8_...`) so it can be rotated in one place.
- Revoke or rotate keys from **Profile → Developer** (personal) or **Settings → API** (org). Revocation is immediate — the next call returns 401.
- Prefer a dedicated org API key for production automations so it is decoupled from any one person's account.

## Frequently Asked Questions

### Can I use n8n Cloud or do I need self-hosted?

Both work. n8n Cloud and self-hosted instances connect to graph8 the same way — the remote endpoint with a Bearer API key. The HTTP Request node method works universally if your version has no MCP node.

### Do I need to do the OAuth browser sign-in like Claude Desktop?

No. The browser OAuth flow is for interactive clients (Claude, Cursor, etc.). n8n is headless and authenticates with an API key in the `Authorization` header instead.

### Are there rate limits on MCP calls from n8n?

Yes — 50 requests per second and 1,000 per minute per org across REST, SDK, and MCP. Add delays in high-volume workflows; a burst over the cap returns HTTP 429 with a `Retry-After` header.

### Can I trigger n8n workflows from graph8?

Use webhooks. Configure an outbound webhook in graph8 that calls your n8n webhook trigger URL when events occur (campaign created, intelligence complete, etc.).

### How do I test MCP calls before building full workflows?

Run a single node with a read-only tool like `g8_list_campaigns` and use n8n's **Execute step** button to inspect the response before wiring it into the rest of the flow.

## Related

- [MCP Overview](https://docs.graph8.com/developers/mcp)
- [What You Can Ask](https://docs.graph8.com/developers/what-you-can-ask/)
- [Automation Platforms](https://docs.graph8.com/developers/automation-platforms/)