MCP APIs

Überblick

Die Sprucely.io MCP APIs öffnen die Dashboard-Plattform für KI-Assistenten und Drittanbieter-Software über das Model Context Protocol (MCP), einen offenen Standard zur Anbindung von KI-Modellen an Tools über HTTP. Jeder MCP-kompatible Client kann gehostete Dashboards erstellen, sie auflisten und einsehen sowie ihnen programmatisch Daten hinzufügen. Über die APIs erstellte Dashboards gehören zu Ihrem Konto und lassen sich im Dienst weiter teilen, einbetten oder bearbeiten. Hinweise zur Einbindung der erstellten Dashboards in Ihre eigene Website finden Sie unter einfache Dashboard-Integration. Wenn Sie Claude verwenden, ist der Sprucely.io-Connector der schnellste Einstieg.

Verbindung

Der MCP-Server wird über Streamable HTTP bereitgestellt unter:

https://www.sprucely.io/mcp

Jeder MCP-Client kann sich mit diesem Endpunkt verbinden. Ein einzelner Befehl registriert den Server beispielsweise in Claude Code:

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

Sie können den Server auch direkt per JSON-RPC 2.0 über HTTP aufrufen. Die meisten MCP-Clients führen den Protokoll-Handshake automatisch durch; die folgende Anfrage listet die verfügbaren Tools mithilfe eines API-Schlüssels auf:

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"}'

Authentifizierung

Anfragen werden über einen Standard-Authorization-Bearer-Header autorisiert. Zwei Arten von Zugangsdaten werden unterstützt.

API-Schlüssel - Erstellen Sie API-Schlüssel im MCP-Bereich Ihres Profils. Schlüssel beginnen mit spr_mcp_, werden bei der Erstellung nur einmal angezeigt und können jederzeit widerrufen werden. Verwenden Sie sie für Skripte, Server und Headless-MCP-Clients.

OAuth 2.1 - Interaktive MCP-Clients können Nutzern stattdessen die Anmeldung mit ihrem Sprucely.io-Konto über OAuth 2.1 ermöglichen. Der Autorisierungsserver unterstützt den Authorization-Code-Flow mit PKCE (erforderlich), Refresh-Tokens und die dynamische Client-Registrierung, sodass sich kompatible Clients anhand der Resource-Metadaten automatisch selbst konfigurieren:

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

Verfügbare Scopes: openid, offline_access, dashboards:read und dashboards:write. Scopes werden pro Tool durchgesetzt: create_dashboard, add_data und set_sharing erfordern dashboards:write und geben ohne diesen Scope einen Fehler zurück. Die übrigen Tools benötigen nur dashboards:read.

Für Clients, die eine manuelle Konfiguration benötigen, lauten die Endpunkte des Autorisierungsservers:

https://www.sprucely.io/oauth/.well-known/openid-configuration - Metadaten des Autorisierungsservers
https://www.sprucely.io/oauth/auth - Autorisierungsendpunkt (PKCE erforderlich)
https://www.sprucely.io/oauth/token - Token-Endpunkt
https://www.sprucely.io/oauth/reg - dynamische Client-Registrierung
https://www.sprucely.io/oauth/jwks - Signaturschlüssel (JWKS)
https://www.sprucely.io/oauth/token/revocation - Token-Widerruf
https://www.sprucely.io/oauth/token/introspection - Token-Introspektion

Tools

Der MCP-Server stellt acht Tools bereit: create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code und storage_status.

Die unten beschriebenen dataset- und dashboard-Parameter sind kein MCP-spezifisches Format - es handelt sich um genau dasselbe Dataset-/Dashboard-JSON, das auf der Seite Datenformat dokumentiert ist und überall sonst im Dienst verwendet wird (die Import-API der eigenständigen einbettbaren Runtime, KI-generierte Layouts und der Dashboard-Editor) - alles, was gegen diese Referenz geschrieben wurde, gilt also auch hier.

create_dashboard - Erstellt ein gehostetes Dashboard aus einem eingebetteten Datensatz und einem Widget-Baum und liefert Ansichts- und Einbettungslinks zurück. Parameter:

name - der Dashboard-Titel (erforderlich)
dataset - der zu visualisierende Datensatz: name, headers (Spaltennamen), types (ein Spaltentyp pro Header - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE oder TIMESTAMP) und entries (Zeilen, jede ein Array von Werten in der Reihenfolge der Header), bis zu 100 Spalten und 50.000 unaggregierte, zeilenbasierte Einträge pro Aufruf (erforderlich). Einträge dürfen nicht vorab aggregiert sein: Senden Sie eine Zeile pro zugrunde liegendem Datensatz und lassen Sie die dataFunction jedes Diagramms Anzahl, Summe, Durchschnitt und Ähnliches zur Renderzeit berechnen.
dashboard - 1 bis 40 Widgets der obersten Ebene, von oben nach unten (erforderlich). Jedes Widget ist entweder ein dash_chart (ein Diagrammtyp - area, bar, cell, dot, hexbin oder line - mit Spaltenzuordnungen für x, y, d und r, einer optionalen dataFunction und einem optionalen Titel), eine dash_table, ein dash_text-Block, ein dash_spacer oder ein dash_stacker_hor/dash_stacker_ver-Container. Stacker verschachteln sich rekursiv - die Kinder eines Stackers können selbst wieder Stacker sein -, um Widgets in Zeilen und Spalten beliebiger Tiefe anzuordnen. Welche Spaltenarten (kategorisch, kontinuierlich oder Datum/Zeit) die Dimensionen x/y/d/r jedes Diagrammtyps akzeptieren und wie die zeitliche Gruppierung einer Datumsspalte mit seasonX/seasonY sie kategorisch macht, ist für jedes Feld über tools/list sowie auf der Seite Datenformat dokumentiert.
theme - optionale dashboardweite Farben (Hintergrund, Text, primäre/dezente/sekundäre Akzente); jedes Widget kann weiterhin seine eigene Farbe oder seinen eigenen Hintergrund überschreiben
shared - ob das Dashboard für jeden mit dem Link einsehbar ist (optional, Standard false). Neue Dashboards sind privat, bis Sie dies auf true setzen oder anschließend set_sharing aufrufen.

Das Ergebnis enthält die dashboardId und datasetId des neuen Dashboards (später benötigt für add_data, get_dataset_schema, set_sharing und get_embed_code) sowie dessen url, viewUrl und den iframe-Einbettungscode. Beispiel - ein Dashboard mit einem Balkendiagramm und einer dashboardweiten Akzentfarbe erstellen:

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 - Liefert Name, Freigabestatus, Datensatz-IDs und Links eines Dashboards. Parameter: dashboardId (erforderlich). Beispiel:

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 - Listet die Dashboards Ihres Kontos auf, sortiert nach letzter Aktualisierung, jeweils mit eigenen datasetIds, sodass ein Datensatz direkt an get_dataset_schema oder add_data übergeben werden kann, ohne einen separaten get_dashboard-Aufruf. Parameter: limit und offset zur Seitennavigation, query für eine Namenssuche ohne Berücksichtigung der Groß- und Kleinschreibung (alle optional). Beispiel:

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 - Fügt Einträge zum Datensatz eines bestehenden Dashboards hinzu; jedes Dashboard, das diesen Datensatz nutzt, aktualisiert sich automatisch. Parameter:

dashboardId - das Dashboard, dem die Daten hinzugefügt werden (erforderlich)
entries - Zeilen, die positionsgenau den Headern des Datensatzes zugeordnet sind, bis zu 50.000 pro Aufruf (erforderlich) - es gilt dieselbe Regel für unaggregierte, zeilenbasierte Einträge wie bei create_dashboard. Rufen Sie zunächst get_dataset_schema auf, wenn Ihnen die exakten Spaltennamen/-reihenfolge des Dashboards nicht bereits bekannt sind. Nutzen Sie es, um große Datensätze in Stapeln zu laden oder Dashboards aktuell zu halten.
run_id - ein optionaler Idempotenzschlüssel für diesen konkreten Stapel (optional). War ein vorheriger add_data-Aufruf mit derselben dashboardId und run_id bereits erfolgreich, liefert ein erneuter Aufruf dieses frühere Ergebnis zurück, statt die Zeilen ein zweites Mal hinzuzufügen - so lässt sich ein Stapel nach einem Timeout oder einer unterbrochenen Verbindung gefahrlos wiederholen. Verwenden Sie pro eigenständigem Stapel eine neue run_id (zum Beispiel eine UUID oder einen Hash ihres Inhalts).

Beispiel:

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 - Liefert Spaltennamen und -typen eines Datensatzes. Nutzen Sie es vor einem Aufruf von add_data (oder beim Erstellen eines neuen Diagramms für denselben Datensatz), wann immer die exakten Spaltennamen/-reihenfolge/-typen nicht bereits bekannt sind, etwa in einer neuen Sitzung oder wenn ein anderer Agent das Dashboard erstellt hat. Parameter: datasetId (erforderlich). Beispiel:

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 - Schaltet den öffentlichen Link eines Dashboards ein oder aus. Das Ausschalten entzieht auch jeder früheren Revision des Dashboards den Zugriff, sodass ein zuvor geteilter Link nicht mehr funktioniert. Parameter: dashboardId und shared (beide erforderlich). Beispiel:

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 - Liefert den teilbaren Ansichtslink und einen iframe-Einbettungscode für ein Dashboard - denselben Link/Einbettungscode, den create_dashboard und set_sharing bereits zurückliefern, für den Fall, dass Sie ihn später erneut allein benötigen. Der Link funktioniert für andere nur, solange das Dashboard geteilt ist. Parameter: dashboardId (erforderlich). Beispiel:

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 - Meldet, wie viel Speicher das Konto bereits genutzt hat und wie viel noch verbleibt - nützlich vor einem create_dashboard- oder add_data-Aufruf, der groß genug ist, um an das Speicherlimit des Tarifs zu stoßen. Keine Parameter. Beispiel:

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
}

Limits und Fehler

Der MCP-Endpunkt akzeptiert 25 Anfragen pro Minute und Client sowie Request-Bodies bis zu 25 MB - laden Sie größere Datensätze in add_data-Stapeln.
Datensätze akzeptieren bis zu 100 Spalten und 50.000 Zeilen pro Aufruf, und ein Dashboard akzeptiert bis zu 40 Widgets auf jeder Verschachtelungsebene. Gespeicherte Dashboards zählen zum Speicherkontingent Ihres Tarifs - rufen Sie storage_status auf, um vor einem umfangreichen create_dashboard- oder add_data-Aufruf den verbleibenden Spielraum zu prüfen.
Es werden Standard-HTTP-Statuscodes verwendet: 401 bei fehlenden oder ungültigen Zugangsdaten (mit einer WWW-Authenticate-Challenge, die auf die Resource-Metadaten verweist), 403 bei widerrufenen oder unzureichenden Zugangsdaten, 413 bei zu großen Anfragen und 429 bei Ratenbegrenzung.