# Agency-API en MCP-server

Een bureau kan zijn eigen AI-assistent (Claude, Cursor, Copilot of een andere MCP-client) het inrichtingswerk in SiteHome laten doen: klanten en hun websites bekijken, een klant toevoegen, een contactpersoon uitnodigen en een website koppelen. De assistent werkt via de MCP-server van SiteHome, met dezelfde regels als de app.

Content bewerken of publiceren kan niet via de API. Publiceren blijft altijd een eigen actie van een persoon in SiteHome, na het controleren van de precieze wijzigingen.

## Een sleutel maken

1. Open in SiteHome **Klanten** en kies **API-sleutels voor AI-assistenten**. Alleen beheerders van het bureau zien dit.
2. Geef de sleutel een naam, kies wat hij mag en hoe lang hij geldig blijft (30, 90 of 365 dagen).
3. Kopieer de sleutel. Je ziet hem maar één keer; SiteHome bewaart alleen een vingerafdruk ervan.

Hetzelfde scherm toont het **adres van de MCP-server** en de recente API-acties van het bureau. Een ingetrokken sleutel werkt meteen niet meer. Een sleutel handelt als de beheerder die hem maakte, en werkt niet meer zodra die persoon geen beheerder van het bureau meer is.

Elk recht geeft toegang tot deze tools:

- **Klanten en websites bekijken**: `list_customers`
- **Klanten toevoegen**: `add_customer`
- **Contactpersonen uitnodigen**: `invite_contact`
- **Websites koppelen**: `inspect_sanity`, `connect_sanity`, `inspect_payload`, `connect_payload`, `inspect_wordpress`, `connect_wordpress`

## SiteHome toevoegen aan je assistent

De server gebruikt Streamable HTTP. Stuur de sleutel mee als `Authorization: Bearer <sleutel>`.

Claude Code:

```text
claude mcp add --transport http sitehome <adres van de MCP-server> --header "Authorization: Bearer <sleutel>"
```

Cursor (`.cursor/mcp.json`):

```json
{"mcpServers": {"sitehome": {"url": "<adres van de MCP-server>", "headers": {"Authorization": "Bearer <sleutel>"}}}}
```

Houd de sleutel buiten gedeelde bestanden en repositories.

## Wat de tools doen

- **list_customers**: klanten met hun websites (CMS, adres, publiceren uit, test of live, laatste keer content gelezen), contactpersonen en open uitnodigingen.
- **add_customer**: een nieuwe klant van het bureau.
- **invite_contact**: een uitnodiging voor een contactpersoon van een klant, voor alle websites van de klant, ook websites die later bijkomen. Je krijgt een link die je zelf deelt; SiteHome stuurt geen e-mail. Er wordt niets toegekend totdat de persoon inlogt met dat e-mailadres en accepteert.
- **inspect_…** en **connect_…**: dezelfde koppeling als in de app, onder een van je klanten. De assistent heeft een CMS-sleutel nodig die je zelf in het CMS van de website hebt gemaakt (zie [Sanity](/nl/docs/sanity), [Payload](/nl/docs/payload), [WordPress](/nl/docs/wordpress)). SiteHome maakt nooit CMS-sleutels of projecten aan. Net als in de app worden alle contentgroepen met items gekoppeld (maximaal 20), tenzij je zelf noemt welke groepen. Een website die al gekoppeld is wordt nooit overgenomen, en bij een nieuwe koppeling staat publiceren uit totdat een beheerder van de website het aanzet.

Je wordt beheerder van een website die met jouw sleutel is gekoppeld, net als wanneer je hem in de app koppelt.

## Voorbeeldopdrachten

```text
Laat mijn SiteHome-klanten zien en vertel welke websites publiceren nog uit hebben staan.
```

```text
Voeg in SiteHome de klant "Bakkerij de Korenschoof" toe en nodig
info@korenschoof.nl uit als redacteur. Geef me de uitnodigingslink.
```

```text
Koppel de Payload-website op https://cms.korenschoof.nl voor de klant
"Bakkerij de Korenschoof". Laat de collectie "settings" weg.
```

## Foutmeldingen

Een geweigerde aanroep geeft een code terug en herhaalt nooit de waarden die je stuurde.

- **KEY_INVALID** (HTTP 401): de sleutel is onbekend, ingetrokken of verlopen, of de maker is geen beheerder van het bureau meer.
- **SCOPE_DENIED**: de sleutel mag deze tool niet gebruiken. Maak een sleutel met dat recht.
- **RATE_LIMITED**: meer dan 30 aanroepen per minuut of 300 per uur met deze sleutel.
- **CUSTOMER_NOT_FOUND**: de klant bestaat niet in je bureau.
- **ALREADY_CONNECTED** of **ADDRESS_IN_USE**: de website staat al in SiteHome. Vraag de beheerder ervan om je uit te nodigen.
- **TOKEN_REJECTED**, **PLUGIN_MISSING**, **SOURCE_UNAVAILABLE**: het CMS accepteerde de sleutel niet of was niet bereikbaar. Zie de pagina van het CMS.
- **INVALID_INPUT:<veld>**: een waarde ontbreekt of is niet geldig.