MCP Server - Revision history

Thomas.sonck at 08:59, 25 July 2026

2026-07-25T08:59:58Z

← Older revision		Revision as of 08:59, 25 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 ==		== 🔌 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:~~		De backend maakt gebruik van het moderne '''Streamable HTTP''' protocol, wat betekent dat het opzetten van sessies, het ophalen van events (SSE) en het verzenden van tool-commando's (POST) allemaal over één en hetzelfde basispad lopen.

	* SSE (~~Server~~-~~Sent Events) Connectie Url: <code><nowiki>https~~:~~//sidefish.app/mcp/sse</nowiki></code>~~		Om als externe agent of service te verbinden, gebruik je het volgende (productie) eindpunt. Vervang eventueel het domein indien je een white-label of specifieke OTAP-omgeving gebruikt:
	* ~~POST Messages~~ Url (voor ~~tool calls, wordt normaal automatisch afgeleid door de MCP client~~): <code><nowiki>https://sidefish.app/mcp~~/messages~~</nowiki></code>		*Base Url (voor zowel POST als GET Streamable HTTP connecties): <code><nowiki>https://sidefish.app/mcp</nowiki></code>
			''(Zorg ervoor dat je client, zoals Claude Desktop of de MCP Inspector, correct ingesteld is op de Streamable HTTP/SSE transport methode).''
	''(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 ==
	Veiligheid en datasegregatie (tenant-isolatie) staan centraal in deze MCP-implementatie:		Veiligheid en datasegregatie (tenant-isolatie) staan centraal in deze MCP-implementatie:
			*Verplichte Authenticatie: Alle MCP verzoeken via <code>/mcp</code> vereisen een geldig OAuth 2.0 JWT Access Token (via de <code>Authorization: Bearer</code> header) óf een API-key ingesteld in de HTTP header (<code>x-api-key</code>). Zonder authenticatie wordt de connectie onmiddellijk afgebroken.
	* 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 (gekoppeld aan een unieke <code>mcp-session-id</code> header). De tools draaien op basis van de rechten van de actieve gebruiker (<code>user._id</code>) en diens organisatie (<code>user.organisation</code>). Alleen indien de gebruiker een systeembeheerder is, zullen speciale admin tools ingeladen worden. Dit garandeert dat state of data nooit weglekt tussen agents of gebruikers.
	* 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.
	* 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==
	== 🛠️ Beschikbare AI Tools ==
	Hieronder vind je een uitgebreid overzicht van alle beschikbare tools (endpoints) die een AI-agent kan gebruiken.		Hieronder vind je een uitgebreid overzicht van alle beschikbare tools (endpoints) die een AI-agent kan gebruiken.
			===1. Klanten Beheer (Customers)===
	=== 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>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.		*<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'').		**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>.		**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.		*<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) ===
	=== 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.
	* <code>create_session_request</code>: Maakt intelligente, geautomatiseerde verzoeken aan (bijv. documenten ondertekenen of vragenlijsten invullen).		**Slimme Notificaties: Door simpele booleans (zoals <code>sendEmailNotification</code> of <code>sendSmsNotification</code>) mee te sturen, stuurt Sidefish automatisch berichten.
	** Automatisch Genereerd: Sidefish genereert zelfstandig de 5-karakter <code>code</code> en de invullink (<code>url</code>). Deze krijg je terug in de response.		**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>).
	** Slimme Notificaties: Door simpele booleans (zoals <code>sendEmailNotification</code> of <code>sendSmsNotification</code>) mee te sturen, stuurt Sidefish automatisch berichten.		*<code>get_sessionrequests</code>: Haalt verzoeken op uit het verleden, optioneel te filteren op <code>status</code>, <code>type</code> of <code>customerId</code>.
	** 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_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>get_sessionrequests</code>: Haalt verzoeken op uit het verleden, optioneel te filteren op <code>status</code>, <code>type</code> of <code>customerId</code>.		*<code>delete_session_request</code>: Annuleert (soft-delete) een actief verzoek op basis van de 5-karakter <code>code</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>.		===3. Portfolio Beheer===
	* <code>delete_session_request</code>: Annuleert (soft-delete) een actief verzoek op basis van de 5-karakter <code>code</code>.		*<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.
	=== 3. Portfolio Beheer ===		*<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_portfolios</code>: Haalt alle portfolio's van jouw organisatie op, eventueel gefilterd op (een deel van) de naam.		*<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>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>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.
	* <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==
	== 🚀 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.
	# De AI gebruikt <code>get_customertemplates</code> om te begrijpen welke klantvelden hij moet uitvragen aan een eindgebruiker.		#Via <code>create_customer</code> wordt de nieuwe klant in het doelsysteem geplaatst.
	# De AI roept <code>get_portfolios</code> aan om te bepalen in welk 'mapje' een klant opgeslagen moet worden.		#De AI gebruikt <code>get_questionlists</code> om de "Onboarding" vragenlijst op te zoeken.
	# Via <code>create_customer</code> wordt de nieuwe klant in het doelsysteem geplaatst.		#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 gebruikt <code>get_questionlists</code> om de "Onboarding" vragenlijst op te zoeken.		#De AI rapporteert succesvol de opgeslagen url (invullink) terug aan de eindgebruiker in de chat!
	# 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!

Thomas.sonck at 14:23, 8 July 2026

2026-07-08T14:23:01Z

← Older revision		Revision as of 14:23, 8 July 2026
Line 5:		Line 5:
	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:		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>		* SSE (Server-Sent Events) Connectie Url: <code><nowiki>https://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>		* POST Messages Url (voor tool calls, wordt normaal automatisch afgeleid door de MCP client): <code><nowiki>https://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).''		''(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).''

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!