Thomas.sonck at 17:36, 5 July 2026

2026-07-05T17:36:57Z

← Older revision		Revision as of 17:36, 5 July 2026
Line 1:		Line 1:
	= Sidefish MCP (Model Context Protocol) API - Wiki =		= Sidefish MCP (Model Context Protocol) API - Wiki =
	Het Sidefish platform is uitgerust met een robuuste Model Context Protocol (MCP) server. Hiermee kunnen externe AI-agents (zoals Claude of custom AI tools) direct communiceren met de Sidefish database om klanten te beheren, portfolio's aan te maken en documentverzoeken (SessionRequests) te versturen.		Het Sidefish platform is uitgerust met een robuuste Model Context Protocol (MCP) server. Hiermee kunnen externe AI-agents (zoals Claude of custom AI tools) direct communiceren met de Sidefish database om klanten te beheren, portfolio's aan te maken en documentverzoeken (SessionRequests) te versturen.

			== 🔌 Connectie & Endpoints ==
			Om als externe agent of service te verbinden, gebruik je de volgende (productie) eindpunten. Vervang eventueel het domein indien je een white-label of specifieke OTAP-omgeving gebruikt:

			* SSE (Server-Sent Events) Connectie Url: <code><nowiki>https://api.sidefish.app/mcp/sse</nowiki></code>
			* POST Messages Url (voor tool calls, wordt normaal automatisch afgeleid door de MCP client): <code><nowiki>https://api.sidefish.app/mcp/messages</nowiki></code>

			''(Zorg ervoor dat je client (zoals Claude Desktop) overweg kan met Server-Sent Events, aangezien dit systeem via HTTP SSE werkt en niet via Standard Input/Output).''
			----

	== 🔐 Beveiliging en Tenant-Isolatie ==		== 🔐 Beveiliging en Tenant-Isolatie ==

Thomas.sonck: Created page with "= Sidefish MCP (Model Context Protocol) API - Wiki = Het Sidefish platform is uitgerust met een robuuste Model Context Protocol (MCP) server. Hiermee kunnen externe AI-agents (zoals Claude of custom AI tools) direct communiceren met de Sidefish database om klanten te beheren, portfolio's aan te maken en documentverzoeken (SessionRequests) te versturen. == 🔐 Beveiliging en Tenant-Isolatie == Veiligheid en datasegregatie (tenant-isolatie) staan centraal in deze MCP-imp..."

2026-07-05T17:34:45Z

Created page with "= Sidefish MCP (Model Context Protocol) API - Wiki = Het Sidefish platform is uitgerust met een robuuste Model Context Protocol (MCP) server. Hiermee kunnen externe AI-agents (zoals Claude of custom AI tools) direct communiceren met de Sidefish database om klanten te beheren, portfolio's aan te maken en documentverzoeken (SessionRequests) te versturen. == 🔐 Beveiliging en Tenant-Isolatie == Veiligheid en datasegregatie (tenant-isolatie) staan centraal in deze MCP-imp..."

New page

= Sidefish MCP (Model Context Protocol) API - Wiki =
Het Sidefish platform is uitgerust met een robuuste Model Context Protocol (MCP) server. Hiermee kunnen externe AI-agents (zoals Claude of custom AI tools) direct communiceren met de Sidefish database om klanten te beheren, portfolio's aan te maken en documentverzoeken (SessionRequests) te versturen.

== 🔐 Beveiliging en Tenant-Isolatie ==
Veiligheid en datasegregatie (tenant-isolatie) staan centraal in deze MCP-implementatie:

* Verplichte Authenticatie: Alle MCP verzoeken via <code>/mcp/sse</code> en <code>/mcp/messages</code> vereisen een geldig OAuth 2.0 JWT Access Token (via een browser sessie) óf een API-key ingesteld in de HTTP header (<code>x-api-key</code>). Zonder authenticatie wordt de connectie onmiddellijk afgebroken.
* Dynamische User Sessies: Elke verbinding lanceert een eigen, virtuele <code>McpServer</code> exclusief voor die sessie. De tools draaien op basis van de rechten van de actieve gebruiker (<code>user._id</code>) en diens organisatie (<code>user.organisation</code>). Dit garandeert dat state of data nooit weglekt tussen agents of gebruikers.
* Waterdichte Tenant-Filtering: Elke actie voert standaard een check uit om er zeker van te zijn dat objecten (zoals klanten of portfolio's) strikt tot de eigen organisatie behoren. Een AI kan ''nooit'' data van een andere tenant (organisatie) lezen of overschrijven.

----

== 🛠️ Beschikbare AI Tools ==
Hieronder vind je een uitgebreid overzicht van alle beschikbare tools (endpoints) die een AI-agent kan gebruiken.

=== 1. Klanten Beheer (Customers) ===

* <code>get_customers</code>: Zoek klanten binnen de portfolio's van jouw organisatie. Biedt krachtige zoekopties waaronder vrij zoeken in dynamische velden (via <code>dataFilters</code>).
* <code>create_customer</code>: Maakt een nieuwe klant aan en koppelt deze automatisch aan de actieve <code>CustomerTemplate</code> van de organisatie.
** Verplicht: <code>portfolioId</code>, <code>data</code> (een object met velden als ''Voornaam'', ''Achternaam'').
** Optioneel: <code>origin</code> (standaard 'manual'), <code>thirdpartyId</code>, <code>notes</code>.
* <code>update_customer</code>: Wijzigt de gegevens van een bestaande klant. Werkt via een partiële update (merge) zodat andere data intact blijft. Je kan hiermee ook een klant verhuizen naar een ander portfolio.

=== 2. Document & Handtekening Verzoeken (SessionRequests) ===

* <code>create_session_request</code>: Maakt intelligente, geautomatiseerde verzoeken aan (bijv. documenten ondertekenen of vragenlijsten invullen).
** Automatisch Genereerd: Sidefish genereert zelfstandig de 5-karakter <code>code</code> en de invullink (<code>url</code>). Deze krijg je terug in de response.
** Slimme Notificaties: Door simpele booleans (zoals <code>sendEmailNotification</code> of <code>sendSmsNotification</code>) mee te sturen, stuurt Sidefish automatisch berichten.
** Sjabloon Fallbacks: Sidefish kijkt zelf naar de ingestelde communicatietemplates van de QuestionList, het Portfolio, of de Organisatie. Wil je dat de AI een eigen tekst schrijft? Stuur dan simpelweg een ''override'' mee (bijv. <code>emailNotificationOverride</code>).
* <code>get_sessionrequests</code>: Haalt verzoeken op uit het verleden, optioneel te filteren op <code>status</code>, <code>type</code> of <code>customerId</code>.
* <code>get_session_request_status</code>: Haalt razendsnel de exacte, real-time status op van een individueel verzoek aan de hand van zijn <code>code</code>.
* <code>delete_session_request</code>: Annuleert (soft-delete) een actief verzoek op basis van de 5-karakter <code>code</code>.

=== 3. Portfolio Beheer ===

* <code>get_portfolios</code>: Haalt alle portfolio's van jouw organisatie op, eventueel gefilterd op (een deel van) de naam.
* <code>create_portfolio</code>: Maakt een nieuw portfolio. Indien geen <code>ownerId</code> is gespecificeerd, wordt de ingelogde AI-gebruiker automatisch de beheerder. Functies zoals <code>isBdayMailingEnabled</code> kunnen hier direct in geconfigureerd worden.
* <code>update_portfolio</code>: Wijzigt de instellingen (zoals taal of naam) van een bestaand portfolio binnen de organisatie.

=== 4. Systeem Configuratie (Hulpmiddelen voor AI) ===

* <code>get_customertemplates</code>: Ideaal voor AI-agents om de datastructuur te leren begrijpen. Haalt het actieve klantsjabloon van de organisatie op (inclusief alle gekoppelde categorieën), zónder backend-specifieke properties zoals <code>showOnListPage</code>. Hiermee kan de AI leren welke archetypes (bijv. GSM of email) er door de organisatie gebruikt worden.
* <code>get_questionlists</code>: Vraag de beschikbare vragenlijsten (QuestionLists) van de organisatie op, zodat de AI de <code>_id</code> van de juiste vragenlijst kan achterhalen voordat hij een <code>create_session_request</code> aanroept.

----

== 🚀 Voorbeeld Workflow voor een AI-Agent ==

# De AI gebruikt <code>get_customertemplates</code> om te begrijpen welke klantvelden hij moet uitvragen aan een eindgebruiker.
# De AI roept <code>get_portfolios</code> aan om te bepalen in welk 'mapje' een klant opgeslagen moet worden.
# Via <code>create_customer</code> wordt de nieuwe klant in het doelsysteem geplaatst.
# De AI gebruikt <code>get_questionlists</code> om de "Onboarding" vragenlijst op te zoeken.
# De AI triggert <code>create_session_request</code> voor de net aangemaakte klant en stuurt hierbij een custom, door AI-geschreven SMS met de invul-link mee via de <code>smsNotificationOverride</code>.
# De AI rapporteert succesvol de opgeslagen url (invullink) terug aan de eindgebruiker in de chat!

MCP Server - Revision history

Thomas.sonck at 17:36, 5 July 2026