# AI-assistenten verbinden (MCP) Your AI Connector levert een officiële **MCP-server** — een Model Context Protocol-eindpunt dat AI-assistenten zoals **Claude Code**, **Claude Desktop**, **Cursor** en je eigen apps in staat stelt om je Your AI Connector-account direct aan te sturen. Vraag het in gewone taal ("list my AI agents", "add this lead", "what did AI cost me this week?") en de assistent roept de Your AI Connector API voor je aan. Het is dezelfde v1-API die u bereikt met een [API-sleutel](api-access.md), geauthenticeerd met uw eigen API-sleutel. De MCP-server bouwt één tool voor elke bewerking in onze gepubliceerde API-specificatie, dus het dekt het grootste deel, maar niet alles, van de v1-API: contacten, berichten, campagnes, AI-agents, aangepaste functies, kennisbank, afspraken, analyses, tags, lijsten, uitzendingen, deals, kanaalverbindingen en subaccounts. Automatiseringen kunnen worden vermeld en gelezen, maar nog niet worden aangemaakt of bewerkt via MCP; maak deze aan in de app. Binnen wat het blootstelt zijn er geen machtigingen per tool en geen standaard alleen-lezen modus, dus de API-sleutel is de volledige toegangscontrole. - **Endpoint:** `https://mcp.youraiconnector.com/mcp` - **Auth:** je Your AI Connector API-sleutel (verzonden als de `X-API-Key` header) - **Vereist:** een abonnement met API-toegang. [Maak een API-sleutel aan →](api-access.md#generating-your-api-key) > Je API-sleutel werkt op **je eigen account**, met dezelfde machtigingen als de > rest van de API — en kan de klantaccounts lezen die je beheert, als je een > agency-abonnement hebt (zie hieronder). Behandel het als een wachtwoord. Je kunt het op elk moment intrekken via > Instellingen → Integraties → API-sleutel, wat de toegang van de assistent onmiddellijk blokkeert. ## Claude Code ```bash claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \ --header "X-API-Key: YOUR_API_KEY" ``` Voer vervolgens `/mcp` uit in Claude Code om te bevestigen dat **ai-connector ✓ connected** wordt weergegeven. Standaard wordt de server toegevoegd op **lokaal** niveau (alleen jij, dit project). Gebruik `--scope user` om deze beschikbaar te maken in al je projecten, of `--scope project` to commit it to a repo's `.mcp.json` voor je team: ```json { "mcpServers": { "ai-connector": { "type": "http", "url": "https://mcp.youraiconnector.com/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` ## Claude Desktop Voeg de server toe als een aangepaste connector. Deze wordt ingesteld in je Claude-account, waardoor hij zowel in Claude Desktop als op claude.ai werkt (gratis Claude-accounts kunnen één aangepaste connector toevoegen). 1. Open **Customize → Connectors**, klik op **+ Add** en vervolgens op **Add custom connector**. 2. Geef de connector een naam en voer `https://mcp.youraiconnector.com/mcp` in als de URL. 3. Kies bij **Authentication** voor **No sign in**. De MCP-server heeft geen inlogpagina: het kiezen van een inlogoptie resulteert in "Couldn't register with … sign-in service". 4. Voeg bij **Request headers** een header toe met de naam `X-API-Key` en je API-sleutel als waarde. 5. Klik op **Add**. Your AI Connector tools verschijnen in het tools-menu van een nieuwe chat. **Geen Request headers-veld?** Je versie van Claude Desktop is verouderd: werk deze bij of gebruik in plaats daarvan het configuratiebestand. Het configuratiebestand (`claude_desktop_config.json`, Settings → Developer → Edit Config) voert alleen programma's op je computer uit en negeert een `url`-vermelding. Daarom is de kleine `mcp-remote`-bridge nodig, waarvoor [Node.js](https://nodejs.org) 18 of nieuwer vereist is: ```json { "mcpServers": { "ai-connector": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.youraiconnector.com/mcp", "--header", "X-API-Key:${AI_CONNECTOR_KEY}" ], "env": { "AI_CONNECTOR_KEY": "YOUR_API_KEY" } } } } ``` Houd `X-API-Key:${AI_CONNECTOR_KEY}` precies zoals geschreven, zonder spatie na de dubbele punt (op Windows splitst een spatie de header), en plaats je sleutel alleen in `env`. Sluit Claude Desktop daarna volledig af (op Windows: rechtsklik op het icoon in het systeemvak → Quit) en open het opnieuw. ## ChatGPT ChatGPT kan op dit moment geen verbinding maken met de MCP-server. Het formulier voor aangepaste connectoren biedt alleen **OAuth** of **Geen authenticatie**, en de Your AI Connector MCP- server logt in met je API-sleutel, die als request header wordt verzonden. Kiezen voor OAuth mislukt met "could not discover OAuth settings", en Geen authenticatie wordt geweigerd omdat elk verzoek de sleutel vereist. Gebruik een assistent waarmee je wel een request header kunt instellen: [Claude Code](#claude-code), [Claude Desktop](#claude-desktop), [Cursor of een andere MCP-client](#cursor--other-mcp-clients), of [de Claude API](#the-claude-api-build-it-into-your-own-app). ChatGPT kan de helpdocumentatie nog steeds lezen zonder verbinding: zie [De helpdocumentatie is ingebouwd](#the-help-docs-are-built-in) voor de openbare `llms.txt`-bestanden. ## Cursor & andere MCP-clients De meeste MCP-compatibele editors gebruiken dezelfde `.mcp.json` vorm als hierboven getoond (een HTTP- server met een `url` en een `X-API-Key` header). Voeg een `ai-connector` server toe die wijst naar `https://mcp.youraiconnector.com/mcp` en plak je API-sleutel in de header. ## De Claude API (inbouwen in je eigen app) Je kunt de MCP-server programmatisch verbinden met de MCP-connector van de Claude API, zodat een agent die je bouwt Your AI Connector-tools kan gebruiken zonder een aparte client: ```json { "model": "claude-opus-4-8", "messages": [{ "role": "user", "content": "List my AI agents" }], "mcp_servers": [ { "type": "url", "name": "ai-connector", "url": "https://mcp.youraiconnector.com/mcp", "authorization_token": "YOUR_API_KEY" } ] } ``` ## Wat u kunt doen Binnen het deel van de v1 API dat de MCP-server blootstelt, kiest de assistent automatisch de juiste tool: - **AI-agents:** weergeven, aanmaken, bijwerken, pauzeren/hervatten, configuratie inspecteren. - **Contacten:** zoeken, aanmaken, labelen, toevoegen aan lijsten, importeren. - **Kennisbank / Veelgestelde vragen:** toevoegen, bewerken, bulkimport, AI-suggesties goedkeuren. - **Berichten:** gesprekken lezen, een bericht sturen naar een contact. - **Afspraken:** weergeven, boeken, annuleren. - **Taken:** aanmaken, voltooien, weergeven. - **Analytics:** berichtstatistieken, kredietverbruik, AI-kosten. - **Kanalen:** verbindingsstatus controleren, een verbindingsstroom starten. ## Vragen over de accounts van je klanten (bureaus) Eén verbinding dekt elk account dat je beheert. Je hoeft geen tweede verbinding toe te voegen per klant: bij een agency-abonnement kan de assistent elk klantaccount onder jou lezen, dus je kunt in één gesprek over ze allemaal vragen stellen. Noem simpelweg de klant: - "Hoeveel contacten heeft Bella's Bistro?" - "Wat heeft AI deze week per klant gekost?" - "Wat is de status van de kanalen van Northside Dental en hoeveel chats zijn er deze week binnengekomen?" Dit omvat het lezen van contacten, berichten, chats, campagnes, afspraken, taken, tags, gebeurtenissen, veelgestelde vragen, kennisbankbronnen, telefoonnummers, kanalen, webhooks en analytics. We controleren of het account echt van jou is voordat er iets wordt uitgevoerd — vragen naar een account dat niet van jou is, resulteert in "niet gevonden". Laat de klant weg en de assistent leest je eigen account, precies zoals voorheen. **Het wijzigen van een klantaccount** werkt op dezelfde manier. Elke actie die een klantaccount accepteert in de API is beschikbaar voor een benoemde klant: het instellen van AI-agents, kennisbanken, aangepaste functies, WhatsApp-sjablonen, toegangspunten, kanaalverbindingen, contacten, tags, uitzendingen, afspraken, deals en taken, en het versturen van berichten. De uitzonderingen zijn acties op agency-niveau, die altijd worden uitgevoerd op uw eigen agency-account: het beheren van de klantaccounts zelf (limieten, functies, prijzen, pauzeren), snapshots, uw team en API-sleutels. Het toevoegen van contacten aan of het verwijderen ervan uit de lijst van een klant is nog niet beschikbaar voor een benoemde klant; doe dit via de eigen sleutel van die klant of in hun account. De [agency API-handleiding](../agency/api-for-agencies.md#where-sub_account_id-is-supported) bevat een lijst met wat wordt ondersteund. ::: neutral-mcp De agency-tools bevinden zich alleen op het standaard, merkloze adres, `https://mcp.youraiconnector.com/mcp`. Een white-label MCP-adres op uw eigen domein (`mcp.youragency.com`) is gebouwd voor uw klanten en bevat deze niet, dus maak verbinding met het standaard, merkloze adres wanneer u klantaccounts beheert. ::: Dit is ook het antwoord voor een klant die **meerdere bedrijven onder één inloggegevens** beheert. Geef elk bedrijf een eigen account en nodig vervolgens het e-mailadres van de klant uit als lid van het team voor al deze accounts: ze loggen één keer in en schakelen tussen hun merken met de accountkiezer in de zijbalk. ### Een agent van een klant testen Vraag de assistent om de agent van een klant uit te proberen ("stuur 'bezorgen jullie op zondag?' naar de Bakkerij-agent van klant X en laat me zien wat deze heeft gedaan"). Het verstuurt een 'Uitproberen'-bericht met jouw agentschap-sleutel en de `sub_account_id` van de klant, wacht af en leest het antwoord plus eventuele acties die de agent heeft ondernomen terug. Er is geen kopie van de agent nodig. Als de assistent zegt dat je geen agentschap-account hebt, is deze verbonden met de sleutel van een klant: verbind deze opnieuw met de sleutel van jouw agentschap-account. Zie [Uitproberen](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant). ## Clients met een tool-limiet ::: neutral-mcp Sommige AI-clients accepteren alleen een server met een beperkt aantal tools. Composio weigert bijvoorbeeld een server die meer dan 500 tools vermeldt en importeert er geen enkele. De volledige agency-verbinding vermeldt er meer dan dat, dus voeg `?tags=` toe aan het adres met alleen de groepen tools die je nodig hebt. Voor een agency die zijn client-accounts wil vermelden, hun contacten, chats en berichten wil lezen en berichten wil verzenden: ``` https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages ``` Dat laadt ongeveer 80 tools. Noem de client in je verzoek en de assistent handelt namens het account van die client, zoals hierboven beschreven. - Scheid groepen met komma's; hoofdletters of kleine letters werken beide. - Om losse tools toe te voegen, vermeld je hun exacte namen met `tools=`, bijvoorbeeld `?tags=Contacts&tools=list_or_get_subaccounts`. Je krijgt elke tool uit beide lijsten. - De help-documentatietools zijn altijd inbegrepen. - De API-sleutel gaat nog steeds in de `X-API-Key`-header (of `Authorization: Bearer YOUR_API_KEY`), nooit in het adres. ::: ## De helpdocumentatie is ingebouwd De MCP-server geeft de assistent toegang tot je **account** en deze **documentatie**. Drie tools lezen de helpdocumentatie live, zodat de assistent kan opzoeken hoe een functie werkt of wat er onlangs is veranderd, in plaats van te gissen: - `docs_search`: vindt de secties die een vraag beantwoorden en retourneert deze met de paginalink. - `docs_read`: leest één pagina volledig, of één sectie ervan. - `docs_list`: somt elke pagina per gebied op. Er hoeft niets te worden ingesteld en de documentatietools hebben nooit toegang tot je accountgegevens. Vraag "hoe werken entry points?" of "wat is er nieuw in automatiseringen?" en de assistent doorzoekt eerst de documentatie. Omdat de tools de helpsite zelf lezen, is een functie bekend bij je assistent zodra de handleiding ervan is gepubliceerd. Een assistent die niet via MCP is verbonden, kan de documentatie nog steeds lezen: verwijs deze naar `https://docs.youraiconnector.com/llms.txt` (een index van elke helppagina met een link naar de Markdown-versie van elke pagina) of `https://docs.youraiconnector.com/llms-full.txt` (de volledige documentatie in één Markdown-bestand). Beide zijn openbaar, vereisen geen sleutel en worden bij elke wijziging in de documentatie opnieuw opgebouwd. ## Je API-sleutel vinden of genereren De API-sleutel die deze verbinding gebruikt, bevindt zich onder **Instellingen → Integraties → API-sleutel** — een eigen sectie, los van Webhooks. Zie [API-toegang](api-access.md#generating-your-api-key) voor de exacte stappen. ## Probleemoplossing - **"Connection refused" of "not found"** — het adres mist de `/mcp` aan het einde. Gebruik `https://mcp.youraiconnector.com/mcp`, niet `https://mcp.youraiconnector.com`. - **`Needs authentication` / 401** — je API-sleutel ontbreekt of is onjuist. Voeg de server opnieuw toe met een geldige `X-API-Key`. - **"Could not discover OAuth settings" (ChatGPT)** — ChatGPT ondersteunt alleen OAuth of geen authenticatie voor aangepaste connectoren, en aangezien de MCP-server een API-sleutel gebruikt, kan ChatGPT voorlopig geen verbinding maken. Zie [ChatGPT](#chatgpt). - **"Couldn't register with … sign-in service" of "add an OAuth Client ID" (Claude Desktop)** — de aangepaste connector is toegevoegd met een inlogoptie. Er is geen OAuth-client-ID om in te voeren: verwijder de connector en voeg deze opnieuw toe met **Authentication → No sign in** en je API-sleutel als `X-API-Key` request header, zoals in [Claude Desktop](#claude-desktop). - **Claude Desktop toont geen tools na het bewerken van het configuratiebestand** — het configuratiebestand negeert een `"url"`-vermelding; gebruik de aangepaste connector of het `mcp-remote`-formulier in [Claude Desktop](#claude-desktop) en sluit de app volledig af en open deze opnieuw. - **Een tool geeft `403` terug** — je abonnement of teamrol staat die actie niet toe; de MCP-server dwingt niets extra's af, het is dezelfde machtigingscontrole als de API. - **Tool not found** — de toollijst wordt live gegenereerd vanuit de API, dus deze komt altijd overeen met de huidige versie; maak opnieuw verbinding om te vernieuwen. - **Een beveiligings- of certificaatwaarschuwing op je eigen domein** — een DNS-record naar ons laten wijzen is op zichzelf niet genoeg: het subdomein moet ook worden geverifieerd in het dashboard voordat het een beveiligde verbinding kan aanbieden. White-label-bureaus kunnen het MCP-adres op hun eigen domein plaatsen (bijv. `mcp.youragency.com`) via de **Custom domain**-kaart onder **Settings → White Labeling** — voeg eerst de CNAME toe bij je registrar, voer daarna de hostnaam in het **MCP domain (AI assistants)**-blok in en klik op **Verify**, dezelfde procedure als voor je andere branded subdomeinen. Het branded adres laat de bureau-tools weg; blijf het standaard, niet-branded adres gebruiken voor die tools. Gebruik tot je branded adres is geverifieerd het standaard, niet-branded adres: dit is veilig om te delen met klanten. --- ## Volgende stappen - [API-toegang](api-access.md) — genereer of roteer de sleutel die deze verbinding gebruikt. - [Webhooks](webhooks.md) — de push-gebaseerde tegenhanger van deze pull-gebaseerde MCP-verbinding.