WFDASH-WEBAPP/docs/n8n-mcp-setup.md

# n8n-MCP Setup

[`.mcp.json`](../.mcp.json) wires the [n8n MCP server](https://docs.n8n.io/advanced-ai/accessing-n8n-mcp-server/) into Claude Code for this project. n8n ships with a built-in HTTP MCP endpoint (`/mcp-server/http`), so there's no extra package to install — just point Claude Code at the URL with a JWT.

Once it's running, you can ask Claude to "create an n8n workflow that ..." and the model can drive n8n directly (create / update / activate workflows, list executions, run nodes, etc.) through MCP tools.

---

## What it does

The n8n MCP server exposes the n8n workflow API as MCP tools. From inside Claude Code you get tools roughly equivalent to:

- `search_workflows`, `get_workflow`, `create_workflow`, `update_workflow`, `delete_workflow`
- `activate_workflow`, `deactivate_workflow`
- `list_executions`, `get_execution`
- `test_workflow` (run a workflow once without activating it)
- SDK/reference tools for building workflow code programmatically

The full list is returned by the `tools/list` JSON-RPC method on the MCP endpoint.

## Prerequisites

1. **n8n running** somewhere the machine running Claude Code can reach (locally, in Docker, or hosted on n8n.cloud / a custom URL).
2. **A MCP-server API key** from n8n. **Important:** this is a different credential from the regular REST API key — it has audience `mcp-server-api`, not `public-api`. Using the wrong one returns `401`.

## Step 1 — Verify the MCP endpoint is reachable

```bash
# Replace <host> with your n8n host (no trailing slash on the URL)
curl -s -X POST "https://<host>/mcp-server/http" \
  -H "Authorization: Bearer <your-mcp-jwt>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl-test","version":"0"}}}'
```

A healthy response looks like:

```
event: message
data: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true},...},"serverInfo":{"name":"n8n MCP Server","version":"1.1.0"},...}}
```

`401` means the JWT is wrong or has the wrong audience. `404` usually means the host is reachable but n8n is not at that path.

## Step 2 — Get a MCP-server API key

In the n8n UI:

1. Click your user icon (top right) → **Settings** → **API**
2. Click **Create an API key**
3. Give it a label (e.g. `claude-code-mcp`)
4. **Copy the key** — n8n only shows it once. The token's `aud` claim must be `mcp-server-api` (decode the JWT at [jwt.io](https://jwt.io) to confirm).

## Step 3 — Update `.mcp.json`

Open [`.mcp.json`](../.mcp.json) (this file is gitignored — see [Security notes](#security-notes)) and set the `url` and `Authorization` header to your instance + key:

```json
{
  "mcpServers": {
    "n8n-mcp": {
      "type": "http",
      "url": "https://<your-n8n-host>/mcp-server/http",
      "headers": {
        "Authorization": "Bearer <your-n8n-mcp-jwt-here>"
      }
    }
  }
}
```

A committed template (no real key) lives at [`.mcp.example.json`](../.mcp.example.json) — copy it to `.mcp.json` and fill in your values:

```bash
cp .mcp.example.json .mcp.json
$EDITOR .mcp.json
```

If your n8n is on a self-signed cert or behind a private CA, add `"NODE_EXTRA_CA_CERTS": "/path/to/ca.pem"` to the server `env` block (this only works for stdio servers, so prefer fixing the cert chain if you can).

## Step 4 — Restart Claude Code

The MCP server is started by Claude Code when the session boots. **Quit and reopen Claude Code** in this project so it picks up `.mcp.json`. You should see `n8n-mcp` listed in the MCP servers status (or invoke `/mcp` to verify).

## Step 5 — Sanity-check

Ask Claude: *"List my n8n workflows"*. If you have none yet it should return an empty list. If it errors, jump to [Troubleshooting](#troubleshooting).

## Connecting n8n to WFDASH

Once n8n can talk to the MCP server in Claude Code, the natural next step is to make n8n talk to WFDASH:

- **n8n as MCP client of WFDASH**: in any n8n workflow, add the **MCP Client Tool** node and point it at `http://localhost:3000/api/mcp` with the bearer token from your WFDASH `AGENT_API_KEY`. You get `orders.list`, `orders.create_from_quote`, `collection_pool.list`, and `order_items.update_status` as drag-and-drop tools.
- **WFDASH → n8n via webhooks**: n8n can expose a webhook URL; WFDASH's REST API can be extended (or a small script can call n8n) to trigger workflows on events (e.g. "quote approved" → kick off an order-creation workflow).
- **Cron in n8n**: schedule a daily digest workflow that calls `orders.list` and posts to Slack / email.

## Troubleshooting

| Symptom | Cause / fix |
| --- | --- |
| `401 Unauthorized` from the MCP endpoint | JWT has the wrong audience. Decode it at jwt.io — you want `aud: mcp-server-api`, not `public-api`. Re-create the key in n8n with the right audience, or use a different key. |
| `404 Not Found` on `/mcp-server/http` | n8n is reachable but the MCP server route is missing. Make sure you're on a recent n8n version (the built-in MCP server shipped in 1.x). |
| MCP tools not showing up in Claude Code | You need to **restart Claude Code** after editing `.mcp.json`. Use `/mcp` to list loaded servers. |
| `ECONNREFUSED` / connection timeout | n8n isn't reachable from where Claude Code is running. `curl` the URL manually first to confirm DNS + port. |
| `self signed certificate` errors | If n8n is behind TLS with a private CA, set `NODE_EXTRA_CA_CERTS` in the server's `env` block (stdio servers only). For HTTP servers, fix the CA chain on the client or n8n side. |
| `tools/list` returns empty `[]` | n8n is up and auth works, but there are no workflows yet (or no permission to see them). Create a test workflow in the n8n UI and re-run. |

## Security notes

- **`.mcp.json` is gitignored.** The real JWT lives only in your local copy. The committed template is [`.mcp.example.json`](../.mcp.example.json) with placeholder values.
- If you ever accidentally commit `.mcp.json`, **rotate the n8n API key immediately** — anyone with the JWT can read and modify every workflow in the instance.
- Prefer a scoped / read-only key when you don't need write access. n8n currently issues a single key per user, so rotate the existing one and re-issue a new one if you need different scopes.
- Treat the n8n API key like any other long-lived secret — it doesn't expire on its own, set a calendar reminder to rotate.