# Connect n8n

With n8n you build workflows where an AI agent reads your calendars and creates events — across **all connected providers at once**: Google, Outlook, iCloud, GMX, WEB.DE and more. No single Google Calendar or Outlook node can do that.

The address (MCP server URL) you will enter below is:

```
https://app.kalender-sync.de/mcp
```

:::note[Prerequisites]
- A Kalender Sync account with [connected calendars](https://docs.kalender-sync.de/en/getting-started/connect-first-calendar/) — reading and [creating events](https://docs.kalender-sync.de/en/ki-assistent/schreibzugriff/) work on every plan, including Free.
- **n8n version 2.19.0 or newer** (Cloud or self-hosted). Older versions drop structured tool results — the agent then falsely claims your calendar list is empty. Find your version in n8n under **Help → About**.
- An **access key** from the app (step 1).
:::

## 1. Create the access and key in Kalender Sync

In the app, open **AI assistant → Connect the assistant** and pick **n8n**. As with every access, you pick the calendars one by one and set the [detail level](https://docs.kalender-sync.de/en/ki-assistent/sichtbarkeit/) per calendar — calendars you don't share do not exist for n8n.

**Create key** gives you your access key (a token starting with `ksa_`). It is **shown only once** — copy it straight into the n8n credential (step 2). Treat it like a password: whoever holds the key holds exactly the access you gave this connection.

## 2. Build the workflow

### The fast way: n8n's AI builder

n8n can generate the workflow from a description. This template works:

```text
Build a workflow with a Chat Trigger connected to an AI Agent.

The AI Agent should use an MCP Client Tool node with these settings:
- Endpoint URL: https://app.kalender-sync.de/mcp
- Server Transport: HTTP Streamable
- Authentication: Header Auth (I will fill in the credential myself)
- Include all available tools

Set the AI Agent's system message to:
"You are a calendar assistant with access to the user's calendars via
Kalender Sync MCP tools. Use list_calendars first to see which calendars
are available and their visibility levels. When asked about availability,
use get_availability. Always mention any warnings the tools return, and
say what your answer does NOT cover."

Use gpt-4.1-mini as the chat model.
```

The builder cannot create credentials — you enter the token by hand afterwards (next section, item 3).

### The manual way: four nodes

1. Add a **Chat Trigger** (or any other trigger — see the workflow ideas below).
2. Add an **AI Agent** node behind it. As the **chat model** we recommend **gpt-4.1-mini** or a comparable non-reasoning model (see Troubleshooting for why).
3. Attach an **MCP Client Tool** node under the agent's **Tool** slot:
   - **Endpoint URL:** `https://app.kalender-sync.de/mcp`
   - **Server Transport:** `HTTP Streamable`
   - **Authentication:** `Header Auth` → create a new credential:
     - **Name:** `Authorization`
     - **Value:** `Bearer ksa_…` (your token from step 1 — the word `Bearer`, one space, then the token)
   - **Tools to include:** `All`
4. Give the agent a **system message** — the one from the builder prompt above works verbatim.

Once everything is wired up, the MCP client node lists the available tools — `list_calendars`, `get_availability`, `search_events` and (with write access enabled) `create_event`, `update_event`, `delete_event`. Technical details for each tool: [tool reference](https://docs.kalender-sync.de/en/ki-assistent/tool-referenz/).

## 3. Test it

Open the chat and ask:

- *"Which calendars do you see, and with which visibility?"* — the agent should name exactly the calendars you shared in step 1, including their detail levels.
- *"Am I free next Tuesday between 9 and 12?"* — availability across all shared calendars.
- *"Create 'test event via n8n' tomorrow at 10 in [calendar name]"* (Basic and up, calendar with write access) — then: *"Delete it again."*

Every call shows up in the [access log](https://docs.kalender-sync.de/en/ki-assistent/#what-stays-in-your-hands) on the **AI assistant** page — you can watch live which tool was called when.

## Workflow ideas

**Availability bot for Slack or Telegram.** Slack/Telegram trigger → AI agent with Kalender Sync tools → reply in the channel. Colleagues (or you, from your phone) ask for free slots in plain language — the agent checks Google, Outlook and GMX in one call.

**Event from a form.** n8n form or webhook trigger (say, a booking request from your website) → the agent extracts date, time and topic → `create_event` in your work calendar. The agent only manages events it created itself — it can [never touch your existing events](https://docs.kalender-sync.de/en/ki-assistent/schreibzugriff/).

**Morning briefing.** Schedule trigger (weekdays at 7) → the agent summarises your day with `search_events` and `get_availability` → email or Slack: "4 events today, biggest gap 1–3 pm."

**Conflict watchdog.** Hourly schedule trigger → the agent checks `get_availability` for double bookings between work and personal calendars → messages you only when something overlaps.

## Troubleshooting

:::caution["I don't see any calendars" — although the tool calls succeed]
In almost every case this is one of two n8n pitfalls, not your access:

1. **n8n older than 2.19.0:** its MCP client drops structured tool results, the agent receives an empty answer and calls the tool in a loop ([n8n issue #26963](https://github.com/n8n-io/n8n/issues/26963)). → Update n8n.
2. **Reasoning model + streaming** (e.g. gpt-5-mini with streaming enabled on the chat trigger): tool results arrive empty at the model. → Switch the model to **gpt-4.1-mini** or similar, or set the chat trigger's response mode from "Streaming" to "When Last Node Finishes".

To check whether your access itself works, look at the **access log** in the app: if it shows successful `list_calendars` calls, the problem is in the workflow, not the access.
:::

- **401 / "Unauthorized":** token mistyped, expired or [revoked](https://docs.kalender-sync.de/en/ki-assistent/#revoke-access). Check the credential: header name exactly `Authorization`, value exactly `Bearer ksa_…` (with the space). If in doubt, create a fresh token in the app.
- **Only SSE offered as transport:** your n8n is older than 1.112. We only support **HTTP Streamable** — please update.
- **A calendar is missing from the list:** it isn't shared with this access — add it in the app under **AI assistant → Edit sharing**. Changes apply immediately, no new token needed.
- **`create_event` fails:** write access is [available on every plan](https://docs.kalender-sync.de/en/ki-assistent/schreibzugriff/) and has to be enabled per calendar.

## Security & control

The same rules as for every assistant access apply to n8n: you decide [per calendar what is visible](https://docs.kalender-sync.de/en/ki-assistent/sichtbarkeit/), every query is logged (never the content of your events), and [revoking in Kalender Sync](https://docs.kalender-sync.de/en/ki-assistent/#revoke-access) kills the token instantly — regardless of what is stored in n8n. Keep the token exclusively in n8n **credentials**, never in node parameters or expressions, so it cannot leak into execution logs.