Tapster MCP-server
De Tapster MCP-server stelt een beperkte set beheeroperaties (tenants, gebruikers, rollen, logs) beschikbaar als Model Context Protocol-tools, bereikbaar als remote connector vanuit de Claude-app. Voor de verbind-stappen zie How-to: MCP-server verbinden in Claude.
De code staat in apps/api/src/api/mcp/. De router is gemount op de publieke,
niet-tenant-gebonden route van de API.
Server
| Item | Waarde |
|---|---|
| MCP-server-URL (productie) | https://apiv7.tapster.nl/mcp |
| Transport | Streamable HTTP, application/json-responses (geen SSE-stream) |
| Auth | OAuth 2.1 + PKCE, login gedelegeerd aan Microsoft Entra |
| Toegang | Alleen @tapster.nl-accounts met de beheerder-rol |
De transport gebruikt bewust enableJsonResponse (complete JSON-response in
plaats van een SSE-stream). Een SSE-stream wordt door de Traefik
buffering-middleware op de API-route afgebroken, wat een 502 gaf op grotere
calls zoals tools/list.
Tools
| Tool | Doel |
|---|---|
list_tenants |
Toont alle tenants (uuid, naam, actief). |
find_user |
Zoekt een gebruiker op e-mail in één tenant of in alle tenants ("all"). |
get_user_access |
Geeft rollen + zichtbare tijdlijn-categorieën voor een e-mail in één tenant of "all". |
list_roles |
Haalt de beschikbare RBAC-rollen op voor één tenant (uuid, isDefault). Gebruik dit vóór update_user_roles. |
create_user |
Maakt een gebruiker aan in één specifieke tenant (niet "all"). |
update_user_roles |
Zet de rollen van een gebruiker in één tenant (PUT /users/:id). Overschrijft de bestaande rollen; geef de rol-uuids uit list_roles. |
deactivate_user |
Deactiveert een gebruiker (DELETE /users/:id) in één tenant of in alle tenants ("all"). Ondersteunt dryRun. |
get_logs |
Haalt prod-logs uit het in-memory /logs-buffer (info+warn). Filtert op tenant, q, level, source, tijdvenster. Zie Platform-logging. |
sync_smoelenboek |
Zet facebook=true voor de opgegeven e-mailadressen en false voor alle andere users in één tenant. dryRun (default true) toont eerst de wijziging. |
Elke tool-aanroep wordt geaudit gelogd (MCP tool-call, source app) met het
e-mailadres van de aanroeper. De tools draaien in-process via withTenantContext
en de bestaande repositories.
Endpoints
Alle endpoints zitten onder de issuer-URL (productie https://apiv7.tapster.nl).
| Methode | Pad | Auth | Doel |
|---|---|---|---|
| POST | /mcp |
Bearer (MCP-access-token) | MCP-transport (JSON-RPC): initialize, tools/list, tools/call. |
| GET | /.well-known/oauth-protected-resource |
publiek | Protected-resource-metadata (RFC 9728): resource + authorization_servers. |
| GET | /.well-known/oauth-authorization-server |
publiek | Authorization-server-metadata (RFC 8414): endpoints, PKCE, registration_endpoint. |
| POST | /mcp/oauth/register |
publiek | Dynamic Client Registration (RFC 7591). Geeft de vaste client (client_id/secret) terug. |
| GET | /mcp/oauth/authorize |
publiek | Start de flow; valideert client + PKCE en redirect naar de Entra-login. |
| GET | /mcp/oauth/entra/callback |
publiek | Entra-callback; controleert de @tapster.nl-beheerder-gate en geeft een auth-code terug aan Claude. |
| POST | /mcp/oauth/token |
client_secret_post | Wisselt code of refresh-token in voor een MCP-access-token (HS256-JWT). |
De @tapster.nl-beheerder-gate wordt afgedwongen in de Entra-callback; het
MCP-access-token wordt daarnaast bij elke /mcp-call geverifieerd.
Env-vars
| Variabele | Doel |
|---|---|
MCP_ISSUER_URL |
Basis-URL van de server (prod-default https://apiv7.tapster.nl). Bepaalt de resource- en endpoint-URLs. |
MCP_OAUTH_CLIENT_ID |
Client-id van de vaste OAuth-client. |
MCP_OAUTH_CLIENT_SECRET |
Client-secret van de vaste OAuth-client. |
MCP_OAUTH_REDIRECT_URIS |
Komma-gescheiden whitelist van toegestane redirect-URIs (default de claude.ai/claude.com-callbacks). |
MCP_JWT_SECRET |
HS256-secret waarmee de MCP-access-tokens worden ondertekend. |
Vereisten in Azure Entra
De login delegeert aan de Entra App Registration achter MCP_OAUTH_CLIENT_ID.
Daar moet deze redirect-URI geregistreerd staan (Authentication → Redirect URIs):
https://apiv7.tapster.nl/mcp/oauth/entra/callback
Ontbreekt die, dan faalt de Microsoft-login met een redirect_uri mismatch en
blijft de connector op “Connect” staan.
Graph-machtigingen (applicatie)
Tools die namens de aanroepende gebruiker Microsoft Graph aanspreken, gebruiken
een app-only client-credentials-token (AZURE_CLIENT_ID/AZURE_CLIENT_SECRET,
scope https://graph.microsoft.com/.default) en adresseren de gebruiker via
/users/{email}/.... De app-registratie heeft daarvoor deze
applicatiemachtigingen nodig (API permissions → Microsoft Graph →
Application, met admin consent; gebruikers hoeven niet opnieuw in te loggen):
| Machtiging | Gebruikt door |
|---|---|
Mail.Send |
exact_send_followup_email |
Calendars.ReadWrite |
outlook_create_event |
Ontbreekt de machtiging, dan geeft Graph een 401/403 en meldt de tool welke machtiging toegekend moet worden.