MCP Server

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.

🔌 Connectie & Endpoints

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.

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:

• Base Url (voor zowel POST als GET Streamable HTTP connecties): https://sidefish.app/mcp

(Zorg ervoor dat je client, zoals Claude Desktop of de MCP Inspector, correct ingesteld is op de Streamable HTTP/SSE transport methode).

---

🔐 Beveiliging en Tenant-Isolatie

Veiligheid en datasegregatie (tenant-isolatie) staan centraal in deze MCP-implementatie:

• Verplichte Authenticatie: Alle MCP verzoeken via /mcp vereisen een geldig OAuth 2.0 JWT Access Token (via de Authorization: Bearer header) óf een API-key ingesteld in de HTTP header (x-api-key). Zonder authenticatie wordt de connectie onmiddellijk afgebroken.
• Dynamische User Sessies: Elke verbinding lanceert een eigen, virtuele McpServer exclusief voor die sessie (gekoppeld aan een unieke mcp-session-id header). De tools draaien op basis van de rechten van de actieve gebruiker (user._id) en diens organisatie (user.organisation). 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.
• 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)

• get_customers: Zoek klanten binnen de portfolio's van jouw organisatie. Biedt krachtige zoekopties waaronder vrij zoeken in dynamische velden (via dataFilters).
• create_customer: Maakt een nieuwe klant aan en koppelt deze automatisch aan de actieve CustomerTemplate van de organisatie.
  • Verplicht: portfolioId, data (een object met velden als Voornaam, Achternaam).
  • Optioneel: origin (standaard 'manual'), thirdpartyId, notes.
• update_customer: 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)

• create_session_request: Maakt intelligente, geautomatiseerde verzoeken aan (bijv. documenten ondertekenen of vragenlijsten invullen).
  • Automatisch Genereerd: Sidefish genereert zelfstandig de 5-karakter code en de invullink (url). Deze krijg je terug in de response.
  • Slimme Notificaties: Door simpele booleans (zoals sendEmailNotification of sendSmsNotification) 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. emailNotificationOverride).
• get_sessionrequests: Haalt verzoeken op uit het verleden, optioneel te filteren op status, type of customerId.
• get_session_request_status: Haalt razendsnel de exacte, real-time status op van een individueel verzoek aan de hand van zijn code.
• delete_session_request: Annuleert (soft-delete) een actief verzoek op basis van de 5-karakter code.

3. Portfolio Beheer

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

4. Systeem Configuratie (Hulpmiddelen voor AI)

• get_customertemplates: 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 showOnListPage. Hiermee kan de AI leren welke archetypes (bijv. GSM of email) er door de organisatie gebruikt worden.
• get_questionlists: Vraag de beschikbare vragenlijsten (QuestionLists) van de organisatie op, zodat de AI de _id van de juiste vragenlijst kan achterhalen voordat hij een create_session_request aanroept.

---

🚀 Voorbeeld Workflow voor een AI-Agent

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