MCP API's

Overzicht

De Sprucely.io MCP API’s ontsluiten het dashboardplatform voor AI-assistenten en software van derden via het Model Context Protocol (MCP), een open standaard voor het koppelen van AI-modellen aan tools over HTTP. Elke MCP-compatibele client kan programmatisch gehoste dashboards maken, deze opvragen en inspecteren, en er data aan toevoegen. Dashboards die via de API’s zijn gemaakt, horen bij uw account en kunnen verder worden gedeeld, ingesloten of bewerkt in de service. Zie voor het insluiten van de resulterende dashboards op uw eigen site de notities over eenvoudige dashboardintegratie. Gebruikt u Claude, dan is de Sprucely.io-connector de snelste manier om te beginnen.

Verbinden

De MCP-server wordt aangeboden via Streamable HTTP op:

https://www.sprucely.io/mcp

Elke MCP-client kan verbinding maken met dit endpoint. Zo registreert bijvoorbeeld één opdracht de server in Claude Code:

claude mcp add --transport http sprucely https://www.sprucely.io/mcp

U kunt de server ook rechtstreeks aanroepen met JSON-RPC 2.0 over HTTP. De meeste MCP-clients voeren de protocolhandshake automatisch uit; het onderstaande verzoek geeft de beschikbare tools weer met behulp van een API-sleutel:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Authenticatie

Verzoeken worden geautoriseerd met een standaard Authorization Bearer-header. Twee typen credentials worden ondersteund.

API-sleutels - Maak API-sleutels aan in het MCP-gedeelte van uw profiel. Sleutels beginnen met spr_mcp_, worden alleen getoond op het moment van aanmaken, en kunnen op elk moment worden ingetrokken. Gebruik ze voor scripts, servers en headless MCP-clients.

OAuth 2.1 - Interactieve MCP-clients kunnen gebruikers in plaats daarvan laten aanmelden met hun Sprucely.io-account via OAuth 2.1. De autorisatieserver ondersteunt de authorization code flow met PKCE (verplicht), refresh tokens en dynamische clientregistratie, zodat compatibele clients zichzelf automatisch configureren op basis van de resource-metadata:

https://www.sprucely.io/.well-known/oauth-protected-resource

Beschikbare scopes: openid, offline_access, dashboards:read en dashboards:write. Scopes worden per tool afgedwongen: create_dashboard, add_data en set_sharing vereisen dashboards:write en geven zonder die scope een foutmelding terug. De overige tools hebben alleen dashboards:read nodig.

Voor clients die handmatige configuratie vereisen, zijn dit de endpoints van de autorisatieserver:

https://www.sprucely.io/oauth/.well-known/openid-configuration - metadata van de autorisatieserver
https://www.sprucely.io/oauth/auth - autorisatie-endpoint (PKCE verplicht)
https://www.sprucely.io/oauth/token - token-endpoint
https://www.sprucely.io/oauth/reg - dynamische clientregistratie
https://www.sprucely.io/oauth/jwks - ondertekeningssleutels (JWKS)
https://www.sprucely.io/oauth/token/revocation - intrekken van tokens
https://www.sprucely.io/oauth/token/introspection - introspectie van tokens

Tools

De MCP-server biedt acht tools: create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code en storage_status.

De dataset- en dashboardparameters hieronder zijn geen MCP-specifiek formaat - het is exact dezelfde dataset-/dashboard-JSON die wordt gedocumenteerd op de pagina Dataformaat en die overal elders in de service wordt gebruikt (de import-API van de standalone insluitbare runtime, AI-gegenereerde indelingen en de dashboardeditor), dus alles wat tegen die referentie is geschreven, geldt ook hier.

create_dashboard - Maakt een gehost dashboard van een inline dataset en een widgetboomstructuur, en retourneert weergave- en insluitlinks. Parameters:

name - de dashboardtitel (verplicht)
dataset - de te visualiseren dataset: name, headers (kolomnamen), types (één databasetype per header - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE of TIMESTAMP) en entries (rijen, elk een array van waarden in de volgorde van de headers), tot 100 kolommen en 50.000 ruwe rijen op recordniveau per aanroep (verplicht). Rijen mogen niet vooraf zijn geaggregeerd: verstuur één rij per onderliggend record, en laat de dataFunction van elke grafiek aantallen, sommen, gemiddelden enzovoort berekenen op het moment van renderen.
dashboard - 1 tot 40 widgets op het hoogste niveau, van boven naar beneden (verplicht). Elke widget is een dash_chart (een grafiektype - area, bar, cell, dot, hexbin of line - kolomtoewijzingen voor x, y, d en r, een optionele dataFunction en een optionele titel), een dash_table, een dash_text-blok, een dash_spacer, of een dash_stacker_hor/dash_stacker_ver-container. Stapelaars worden recursief genest - de eigen children van een stapelaar kunnen op hun beurt weer stapelaars bevatten - om widgets te ordenen in rijen en kolommen van willekeurige diepte. Welke kolomsoorten (categorisch, continu of datum/tijd) elk grafiektype accepteert voor de dimensies x/y/d/r, en hoe het groeperen van een datumkolom in tijdsperioden met seasonX/seasonY deze categorisch maakt, wordt bij elk veld gedocumenteerd via tools/list en op de pagina Dataformaat.
theme - optionele dashboardbrede kleuren (achtergrond, tekst, primaire/subtiele/secundaire accenten); elke widget kan nog steeds zijn eigen kleur of achtergrond overschrijven
shared - of het dashboard zichtbaar is voor iedereen met de link (optioneel, standaard false). Nieuwe dashboards zijn privé totdat u dit instelt op true of achteraf set_sharing aanroept.

Het resultaat bevat de dashboardId en datasetId van het nieuwe dashboard (nodig voor add_data, get_dataset_schema, set_sharing en get_embed_code achteraf), plus de url, viewUrl en het iframe-insluitfragment. Voorbeeld - een dashboard maken met een staafdiagram en een dashboardbrede accentkleur:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_dashboard",
      "arguments": {
        "name": "Regional Sales",
        "dataset": {
          "name": "Sales",
          "headers": ["region", "revenue"],
          "types": ["VARCHAR", "DOUBLE"],
          "entries": [
            ["North", 1250.5],
            ["South", 980.25],
            ["East", 1420.0]
          ]
        },
        "dashboard": {
          "type": "dash",
          "children": [
            { "type": "dash_chart", "chartType": "bar", "x": "region", "d": "revenue", "dataFunction": "sum", "title": "Revenue by region" }
          ]
        },
        "theme": { "themePrimary": "#6E2BDC" }
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "datasetId": "data_e5f6g7h8",
  "name": "Regional Sales",
  "shared": false,
  "rows": 3,
  "columns": 2,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

get_dashboard - Retourneert de naam, deelstatus, dataset-ID’s en links van een dashboard. Parameter: dashboardId (verplicht). Voorbeeld:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_dashboard",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "name": "Regional Sales",
  "shared": false,
  "archived": false,
  "datasetIds": ["data_e5f6g7h8"],
  "source": "mcp",
  "updatedAt": "2026-07-29T10:15:00.000Z",
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

list_dashboards - Geeft de dashboards in uw account weer, gesorteerd op laatste update, elk met zijn eigen datasetIds zodat een dataset rechtstreeks kan worden doorgegeven aan get_dataset_schema of add_data zonder aparte aanroep van get_dashboard. Parameters: limit en offset voor paginering, query voor een niet-hoofdlettergevoelig naamfilter (allemaal optioneel). Voorbeeld:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "list_dashboards",
      "arguments": {
        "limit": 10,
        "query": "sales"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "total": 1,
  "limit": 10,
  "offset": 0,
  "hasMore": false,
  "dashboards": [
    {
      "dashboardId": "dash_a1b2c3d4",
      "name": "Regional Sales",
      "shared": false,
      "datasetIds": ["data_e5f6g7h8"],
      "source": "mcp",
      "updatedAt": "2026-07-29T10:15:00.000Z",
      "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
      "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
      "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
    }
  ]
}

add_data - Voegt rijen toe aan de dataset van een bestaand dashboard; elk dashboard dat de dataset gebruikt, wordt automatisch vernieuwd. Parameters:

dashboardId - het dashboard waaraan wordt toegevoegd (verplicht)
entries - rijen die positioneel zijn afgestemd op de headers van de dataset, tot 50.000 per aanroep (verplicht) - dezelfde regel voor ruwe rijen op recordniveau als bij create_dashboard is van toepassing. Roep eerst get_dataset_schema aan als u de exacte kolomnamen/volgorde van het dashboard nog niet kent. Gebruik dit om grote datasets in batches te laden of om dashboards actueel te houden.
run_id - een optionele idempotentiesleutel voor deze specifieke batch (optioneel). Als een eerdere aanroep van add_data met dezelfde dashboardId en run_id al is geslaagd, retourneert een herhaalde aanroep dat eerdere resultaat in plaats van de rijen een tweede keer toe te voegen, zodat een batch veilig opnieuw kan worden geprobeerd na een timeout of verbroken verbinding - gebruik een nieuwe run_id per afzonderlijke batch (bijvoorbeeld een UUID of een hash van de inhoud).

Voorbeeld:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "add_data",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4",
        "entries": [
          ["West", 875.0]
        ],
        "run_id": "batch-2026-07-29T10:20:00Z"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "datasetId": "data_e5f6g7h8",
  "addedRows": 1,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}
# Calling again later with the same dashboardId + run_id (e.g. after a dropped
# connection) is safe: the rows are not appended twice, and the response also
# carries "duplicate": true instead of appending again.

get_dataset_schema - Retourneert de kolomnamen en -typen van een dataset. Gebruik dit voordat u add_data aanroept (of een nieuwe grafiek bouwt op dezelfde dataset) wanneer de exacte kolomnamen/volgorde/typen nog niet bekend zijn, bijvoorbeeld in een nieuwe sessie of wanneer een andere agent het dashboard heeft gemaakt. Parameter: datasetId (verplicht). Voorbeeld:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "get_dataset_schema",
      "arguments": {
        "datasetId": "data_e5f6g7h8"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "datasetId": "data_e5f6g7h8",
  "headers": ["region", "revenue"],
  "types": ["VARCHAR", "DOUBLE"]
}

set_sharing - Schakelt de openbare link van een dashboard in of uit. Uitschakelen trekt ook de toegang voor elke eerdere revisie van het dashboard in, zodat een link die in het verleden is gedeeld, niet meer werkt. Parameters: dashboardId en shared (beide verplicht). Voorbeeld:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "set_sharing",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4",
        "shared": true
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "shared": true,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

get_embed_code - Retourneert de deelbare weergavelink en een iframe-insluitfragment voor een dashboard - dezelfde link/insluitcode die create_dashboard en set_sharing al retourneren, voor wanneer deze afzonderlijk opnieuw nodig zijn. De link werkt voor anderen alleen zolang het dashboard wordt gedeeld. Parameter: dashboardId (verplicht). Voorbeeld:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "get_embed_code",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "shared": true,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

storage_status - Rapporteert hoeveel opslag het account heeft gebruikt en hoeveel er nog resteert, nuttig voordat u een create_dashboard- of add_data-aanroep doet die groot genoeg is om de opslaglimiet van het abonnement te riskeren. Geen parameters. Voorbeeld:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
      "name": "storage_status",
      "arguments": {}
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "used": 5242880,
  "limit": 104857600,
  "percent": 5,
  "plan": "Regular",
  "over": 0,
  "blocked": false
}

Limieten en fouten

Het MCP-endpoint accepteert 25 verzoeken per minuut per client en requestbodies tot 25 MB - laad grotere datasets in batches via add_data.
Datasets accepteren tot 100 kolommen en 50.000 rijen per aanroep, en een dashboard accepteert tot 40 widgets op elk niveau van nesting. Opgeslagen dashboards tellen mee voor het opslagquotum van uw abonnement - roep storage_status aan om de resterende ruimte te controleren voordat u een grote create_dashboard- of add_data-aanroep doet.
Er worden standaard HTTP-statuscodes gebruikt: 401 voor ontbrekende of ongeldige credentials (met een WWW-Authenticate-challenge die verwijst naar de resource-metadata), 403 voor ingetrokken of onvoldoende credentials, 413 voor te grote verzoeken en 429 bij rate limiting.